
                                              University of Amsterdam

                                              Human-Computer Studies
                                                (HCS, formerly SWI)

                                                Kruislaan 419, 1098
                                                   VA  Amsterdam
                                                  The Netherlands
                                              Tel.  (+31) 20 5256121

                         SSWWII--PPrroolloogg 55..66

                        RReeffeerreennccee MMaannuuaall
             _U_p_d_a_t_e_d _f_o_r _v_e_r_s_i_o_n _5_._6_._5_8_, _J_u_l_y _2_0_0_8

                         _J_a_n _W_i_e_l_e_m_a_k_e_r
                    wielemak@science.uva.nl
                   http://www.swi-prolog.org

SWI-Prolog  is  a Prolog  implementation based  on a  subset of
the  WAM (Warren Abstract  Machine).   SWI-Prolog was developed
as  an _o_p_e_n  Prolog environment,  providing a powerful  and bi-
directional  interface to C in an era this was unknown to other
Prolog  implementations.  This environment  is required to deal
with  XPCE,  an object-oriented  GUI system  developed  at SWI.
XPCE  is used at SWI for the development of knowledge-intensive
graphical  applications.   As  SWI-Prolog became  more popular,
a   large  user-community  provided  requirements  that  guided
its  development.    Compatibility,  portability,  scalability,
stability  and  providing  a  powerful development  environment
have   been  the  most  important  requirements.     Edinburgh,
Quintus,  SICStus and the ISO-standard guide the development of
the  SWI-Prolog primitives.  This document gives an overview of
the features, system limits and built-in predicates.

Copyright Oc 1990--2008, University of Amsterdam


CChhaapptteerr 11..  IINNTTRROODDUUCCTTIIOONN


11..11 SSWWII--PPrroolloogg

SWI-Prolog started back in  1986 with the requirement for a  Prolog that
could handle recursive interaction with the C-language:   Prolog calling
C and  C calling  Prolog recursively.   Those  days Prolog systems  were
very aware  of its environment  and we needed such  a system to  support
interactive  applications.   Since  then,  SWI-Prolog's development  has
been guided  by requests from the  user community, especially  focussing
on (in arbitrary  order) interaction with the environment,  scalability,
(I/O)  performance,  standard  compliance,   teaching  and  the  program
development environment.

SWI-Prolog  is   based  on   a  very  simple   Prolog  virtual   machine
called ZIP  [Bowen _e_t _a_l_., 1983, Neumerkel, 1993]  which defines only  7
instructions.  Prolog can easily be compiled into  this language and the
abstract machine code is  easily decompiled back into Prolog.  As  it is
also possible to wire a standard 4-port debugger in  the virtual machine
there is  no need  for a  distinction between  compiled and  interpreted
code.    Besides simplifying  the  design of  the Prolog  system  itself
this  approach has  advantages for  program development:   the  compiler
is  simple and  fast,  the  user does  not  have  to decide  in  advance
whether debugging is  required and the system only runs  slightly slower
when in  debug mode.    The price  we have  to pay  is some  performance
degradation (taking  out the debugger from  the VM interpreter  improves
performance by about  20%) and somewhat additional memory usage  to help
the decompiler and debugger.

SWI-Prolog  extends  the  minimal  set  of   instructions  described  in
[Bowen _e_t _a_l_., 1983]  to improve  performance.    While  extending  this
set care  has been  taken to  maintain the  advantages of  decompilation
and  tracing of  compiled  code.    The extensions  include  specialised
instructions  for unification,  predicate  invocation,  some  frequently
used built-in  predicates, arithmetic, and  control (;/2, |/2),  if-then
(->/2) and negation-by-failure (\+/1).


11..11..11 BBooookkss aabboouutt PPrroolloogg

This manual does not  describe the full syntax and semantics  of Prolog,
nor how  one should  write a  program in Prolog.    These subjects  have
been  described extensively  in  the literature.    See  [Bratko, 1986],
[Sterling & Shapiro, 1986],   and   [Clocksin & Melish, 1987].       For
more  advanced  Prolog  material  see  [O'Keefe, 1990].      Syntax  and
standard  operator declarations  confirm  to the  `Edinburgh  standard'.
Most  built  in  predicates  are  compatible  with  those  described  in
[Clocksin & Melish, 1987].      SWI-Prolog  also  offers  a  number   of
primitive  predicates compatible  with  Quintus Prolog  [Qui, 1997]  and
BIM_Prolog [BIM, 1989].

ISO  compliant  predicates  are based  on  ``Prolog:    The  Standard'',
[Deransart _e_t _a_l_., 1996], validated using [Hodgson, 1998].


11..22 SSttaattuuss

This manual describes  version 5.6 of SWI-Prolog.   SWI-Prolog has  been
used now for many  years.  The application range includes  Prolog course
material,  meta-interpreters, simulation  of parallel  Prolog,  learning
systems,  natural  language  processing,  complex  interactive  systems,
web-server  and web-server  components.    Although  in  our  experience
rather obvious and  critical bugs can remain unnoticed for  a remarkable
long period, we assume  the basic Prolog system is fairly stable.   Bugs
can be expected in infrequently used built-in predicates.

Some bugs are known to  the author.  They are described as  footnotes in
this manual.


11..33 CCoommpplliiaannccee ttoo tthhee IISSOO ssttaannddaarrdd

SWI-Prolog 3.3.0 implements  all predicates described in ``Prolog:   The
Standard'' [Deransart _e_t _a_l_., 1996].

Exceptions  and warning  are still  weak.    Some SWI-Prolog  predicates
silently  fail on  conditions where  the ISO  specification requires  an
exception  (functor/3 for  example).    Some predicates  print  warnings
rather than raising an  exception.  All predicates where  exceptions may
be  caused due  to a  correct program  operating in  an imperfect  world
(I/O, arithmetic,  resource overflows)  should behave  according to  the
ISO standard.   In other  words:  SWI-Prolog  should be able to  execute
any program  conforming to [Deransart _e_t _a_l_., 1996]  that does not  rely
on exceptions generated by errors in the program.


11..44 SShhoouulldd yyoouu bbee uussiinngg SSWWII--PPrroolloogg??

There are a number of reasons why you better  choose a commercial Prolog
system, or another academic product:

  o _S_W_I_-_P_r_o_l_o_g _i_s _n_o_t _s_u_p_p_o_r_t_e_d
    Although  I usually fix bugs shortly  after a bug report arrives,  I
    cannot  promise anything.   Now that the  sources are provided,  you
    can always dig into them yourself.

  o _M_e_m_o_r_y _r_e_q_u_i_r_e_m_e_n_t_s _a_n_d _p_e_r_f_o_r_m_a_n_c_e _a_r_e _y_o_u_r _f_i_r_s_t _c_o_n_c_e_r_n_s
    A  number  of  commercial compilers  are  more  keen on  memory  and
    performance  than SWI-Prolog.   I do not  wish to sacrifice some  of
    the  nice features of the system, nor its portability to  compete on
    raw performance.

  o _Y_o_u _n_e_e_d _f_e_a_t_u_r_e_s _n_o_t _o_f_f_e_r_e_d _b_y _S_W_I_-_P_r_o_l_o_g
    In  this case you  may wish to  give me suggestions for  extensions.
    If  you  have great  plans, please  contact me  (you  might have  to
    implement them yourself however).

On the other hand, SWI-Prolog offers some nice facilities:

  o _N_i_c_e _e_n_v_i_r_o_n_m_e_n_t
    This includes `Do  What I Mean', automatic completion of atom names,
    history mechanism and  a tracer that operates on single key-strokes.
    Interfaces  to  some  standard  editors are  provided  (and  can  be
    extended), as well as a facility to maintain programs (see make/0).

  o _V_e_r_y _f_a_s_t _c_o_m_p_i_l_e_r
    Even  very  large applications  can  be loaded  in seconds  on  most
    machines.  If  this is not enough, there is a Quick Load Format that
    is slightly more compact and loading is almost always I/O bound.

  o _T_r_a_n_s_p_a_r_e_n_t _c_o_m_p_i_l_e_d _c_o_d_e
    SWI-Prolog  compiled code can be  treated just as interpreted  code:
    you  can list it, trace  it, etc.  This  implies you do not have  to
    decide  beforehand whether a module  should be loaded for  debugging
    or  not.  Also, performance  is much better than the  performance of
    most interpreters.

  o _P_r_o_f_i_l_i_n_g
    SWI-Prolog offers tools  for performance analysis, which can be very
    useful  to optimise  programs.   Unless you  are very familiar  with
    Prolog  and Prolog  performance  considerations this  might be  more
    helpful than a better compiler without these facilities.

  o _F_l_e_x_i_b_i_l_i_t_y
    SWI-Prolog  can  easily   be  integrated  with  C,  supporting  non-
    determinism  in Prolog calling  C as well  as C calling Prolog  (see
    section  9).  It can also be _e_m_b_e_d_d_e_d embedded in  external programs
    (see  section 9.7).  System  predicates can be redefined locally  to
    provide compatibility with other Prolog systems.

  o _I_n_t_e_g_r_a_t_i_o_n _w_i_t_h _X_P_C_E
    SWI-Prolog   offers  a   tight  integration  to   the  Object   Ori-
    ented   Package  for   User  Interface   Development,  called   XPCE
    [Anjewierden & Wielemaker, 1989].    XPCE  allows you  to  implement
    graphical  user  interfaces  that are  source-code  compatible  over
    Unix/X11,  Win32  (Windows  95/98/ME  and NT/2000/XP)  and  MacOS  X
    (darwin).


11..55 TThhee XXPPCCEE GGUUII ssyysstteemm ffoorr PPrroolloogg

The  XPCE GUI  system  for dynamically  typed  languages has  been  with
SWI-Prolog for  a long time.   It is  developed by Anjo Anjewierden  and
Jan  Wielemaker from  the department  of SWI,  University of  Amsterdam.
It  aims at  a  high-productive  development environment  for  graphical
applications based on Prolog.

Object  oriented  technology has  proven  to  be a  suitable  model  for
implementing GUIs, which  typically deal with things Prolog is  not very
good  at:   event-driven  control  and global  state.    With  XPCE,  we
designed  a system  that has  similar characteristics  that make  Prolog
such  a powerful  tool:   dynamic typing,  meta-programming and  dynamic
modification of the running system.

XPCE is  an object-system written  in the C-language.   It provides  for
the implementation of methods  in multiple languages.  New  XPCE classes
may be defined from Prolog using a simple, natural syntax.   The body of
the method is executed  by Prolog itself, providing a  natural interface
between the two systems.  Below is a very simple class definition.

:- pce_begin_class(prolog_lister, frame,
                   "List Prolog predicates").

initialise(Self) :->
        "As the C++ constructor"::
        send_super(Self, initialise, 'Prolog Lister'),
        send(Self, append, new(D, dialog)),
        send(D, append,
             text_item(predicate, message(Self, list, @arg1))),
        send(new(view), below, D).

list(Self, From:name) :->
        "List predicates from specification"::
        (   catch(term_to_atom(Term, From), _, fail)
        ->  get(Self, member, view, V),
            current_output(Old),
            pce_open(V, write, Fd),
            set_output(Fd),
            listing(Term),
            close(Fd),
            set_output(Old)
        ;   send(Self, report, error, 'Syntax error')
        ).

:- pce_end_class.

test :- send(new(prolog_lister), open).

Its  165  built-in   classes  deal  with  the  meta-environment,   data-
representation  and---of  course---graphics.     The   graphics  classes
concentrate on direct-manipulation of diagrammatic representations.

AAvvaaiillaabbiilliittyy.. XPCE  runs on  most  Unixtm platforms,  Windows  95/98/ME,
Windows NT/2000/XP and MacOS  X (using X11).  In the past,  versions for
Quintus- and SICStus Prolog as well as some Lisp  dialects have existed.
After discontinuing  active Lisp  development at SWI  the Lisp  versions
have died.   Active development on the Quintus and SICStus  versions has
been stopped  due to lack  of standardisation  in the Prolog  community.
If adequate  standards emerge  we are  happy to  actively support  other
Prolog implementations.

IInnffoo.. further    information   is    available   from    http://www.swi-
prolog.org/packages/xpce/ or by E-mail to info@www.swi-prolog.org.


11..66 RReelleeaassee NNootteess

Collected release-notes.   This section  only contains some  highlights.
Smaller changes to especially  older releases have been removed.   For a
complete log, see the file ChangeLog from the distribution.


11..66..11 VVeerrssiioonn 11..88 RReelleeaassee NNootteess

Version  1.8 offers  a stack-shifter  to  provide dynamically  expanding
stacks  on machines  that  do  not offer  operating-system  support  for
implementing dynamic stacks.


11..66..22 VVeerrssiioonn 11..99 RReelleeaassee NNootteess

Version  1.9  offers  better portability  including  an  MS-Windows  3.1
version.  Changes to the Prolog system include:

  o _R_e_d_e_f_i_n_i_t_i_o_n _o_f _s_y_s_t_e_m _p_r_e_d_i_c_a_t_e_s
    Redefinition  of system  predicates  was allowed  silently in  older
    versions.    Version 1.9  only allows it  if the  new definition  is
    headed by a :- redefine_system_predicate/1 directive.top-level

  o _`_A_n_s_w_e_r_' _r_e_u_s_e
    The  top-level maintains a table  of bindings returned by  top-level
    goals  and  allows for  reuse  of these  bindings by  prefixing  the
    variables with the $ sign.  See section 2.8.

  o _B_e_t_t_e_r _s_o_u_r_c_e _c_o_d_e _a_d_m_i_n_i_s_t_r_a_t_i_o_n
    Allows  for proper updating of multifile predicates and  finding the
    sources of individual clauses.


11..66..33 VVeerrssiioonn 22..00 RReelleeaassee NNootteess

New features offered:

  o _3_2_-_b_i_t _V_i_r_t_u_a_l _M_a_c_h_i_n_e
    Removes various limits and improves performance.

  o _I_n_l_i_n_e _f_o_r_e_i_g_n _f_u_n_c_t_i_o_n_s
    `Simple'  foreign predicates no  longer build a Prolog  stack-frame,
    but are directly  called from the VM. Notably provides a speedup for
    the test predicates such as var/1, etc.

  o _V_a_r_i_o_u_s _c_o_m_p_a_t_i_b_i_l_i_t_y _i_m_p_r_o_v_e_m_e_n_t_s

  o _S_t_r_e_a_m _b_a_s_e_d _I_/_O _l_i_b_r_a_r_y
    All  SWI-Prolog's I/O is now  handled by the stream-package  defined
    in  the foreign include file SWI-Stream.h.   Physical I/O of  Prolog
    streams  may be  redefined through the  foreign language  interface,
    facilitating much simpler integration in window environments.


11..66..44 VVeerrssiioonn 22..55 RReelleeaassee NNootteess

Version  2.5  is  an  intermediate release  on  the  path  from  2.1  to
3.0.    All  changes are  to  the foreign-language  interface,  both  to
user- and system-predicates implemented  in the C-language.  The  aim is
twofold.   First of all  to make garbage-collection and  stack-expansion
(stack-shifts)  possible  while  foreign  code  is  active  without  the
C-programmer having  to worry  about locking  and unlocking  C-variables
pointing  to Prolog  terms.    The new  approach is  closely  compatible
to the  Quintus and  SICStus Prolog  foreign interface  using the  +term
argument specification (see their respective manuals).   This allows for
writing foreign  interfaces that  are easily portable  over these  three
Prolog platforms.

Apart from  various bug fixes  listed in the  ChangeLog file, these  are
the main changes since 2.1.0:

  o _I_S_O _c_o_m_p_a_t_i_b_i_l_i_t_y
    Many   ISO  compatibility  features   have  been  added:     open/4,
    arithmetic functions, syntax, etc.

  o _W_i_n_3_2
    Many  fixes for the Win32 (NT,  '95 and win32s) platforms.   Notably
    many  problems related  to pathnames  and a problem  in the  garbage
    collector.

  o _P_e_r_f_o_r_m_a_n_c_e
    Many  changes to  the clause  indexing system:   added  hash-tables,
    lazy computation of the index information, etc.

  o _P_o_r_t_a_b_l_e _s_a_v_e_d_-_s_t_a_t_e_s
    The   predicate  qsave_program/[1,2] allows  for   the  creating  of
    machine independent saved-states that load very quickly.


11..66..55 VVeerrssiioonn 22..66 RReelleeaassee NNootteess

Version 2.6  provides a stable implementation  of the features added  in
the 2.5.x  releases, but  at the same  time implements  a number of  new
features that may have impact on the system stability.

  o _3_2_-_b_i_t _i_n_t_e_g_e_r _a_n_d _d_o_u_b_l_e _f_l_o_a_t _a_r_i_t_h_m_e_t_i_c
    The  biggest change is the  support for full 32-bit signed  integers
    and  raw  machine-format  double precision  floats.    The  internal
    data  representation as well as  the arithmetic instruction set  and
    interface to the arithmetic functions has been changed for this.

  o _E_m_b_e_d_d_i_n_g _f_o_r _W_i_n_3_2 _a_p_p_l_i_c_a_t_i_o_n_s
    The  Win32 version has been reorganised.   The Prolog kernel is  now
    implemented  as Win32  DLL that may  be embedded in  C-applications.
    Two front ends  are provided, one for window-based operation and one
    to run as a Win32 console application.

  o _C_r_e_a_t_i_n_g _s_t_a_n_d_-_a_l_o_n_e _e_x_e_c_u_t_a_b_l_e_s
    Version  2.6.0 can create  stand-alone executables by attaching  the
    saved-state to the emulator.  See qsave_program/2.


11..66..66 VVeerrssiioonn 22..77 RReelleeaassee NNootteess

Version 2.7  reorganises the  entire data-representation  of the  Prolog
data  itself.   The  aim is  to remove  most of  the  assumption on  the
machine's memory  layout to  improve portability in  general and  enable
embedding on  systems where the memory  layout may depend on  invocation
or on how the executable is linked.  The latter  is notably a problem on
the Win32 platforms.  Porting to 64-bit architectures is feasible now.

Furthermore, 2.7 lifts the  limits on arity of predicates and  number of
variables in  a clause considerably and  allow for further expansion  at
minimal cost.


11..66..77 VVeerrssiioonn 22..88 RReelleeaassee NNootteess

With version  2.8, we declare  the data-representation changes of  2.7.x
stable.   Version  2.8 exploits  the changes  of 2.7  to support  64-bit
processors like the DEC Alpha.  As of  version 2.8.5, the representation
of  recorded  terms  has  changed,  and  terms   on  the  heap  are  now
represented  in a  compiled format.    SWI-Prolog no  longer limits  the
use of malloc()  or uses assumptions on  the addresses returned by  this
function.


11..66..88 VVeerrssiioonn 22..99 RReelleeaassee NNootteess

Version  2.9  is  the next  step  towards  version  3.0,  improving  ISO
compliance  and introducing  ISO  compliant  exception handling.     New
are catch/3, throw/1, abolish/1, write_term/[2,3], write_canonical/[1,2]
and  the  C-functions PL_exception() and  PL_throw().    The  predicates
display/[1,2] and  displayq/[1,2] have  been moved to  backcomp, so  old
code referring to them will autoload them.

The interface  to PL_open_query()  has changed.   The  _d_e_b_u_g argument  is
replaced  by a  bitwise or'ed  _f_l_a_g_s argument.    The  values FALSE  and
TRUE have their familiar meaning, making old code  using these constants
compatible.   Non-zero values  other than TRUE  (1) will be  interpreted
different.


11..66..99 VVeerrssiioonn 33..00 RReelleeaassee NNootteess

Complete  redesign   of  the   saved-state  mechanism,   providing   the
possibility of  `program resources'.   See  resource/3, open_resource/3,
and qsave_program/[1,2].


11..66..1100 VVeerrssiioonn 33..11 RReelleeaassee NNootteess

Improvements   on  exception-handling.       Allows  relating   software
interrupts (signals)  to exceptions,  handling signals in  Prolog and  C
(see on_signal/3  and PL_signal()).    Prolog stack  overflows now  raise
the resource_error  exception and thus  can be handled  in Prolog  using
catch/3.


11..66..1111 VVeerrssiioonn 33..33 RReelleeaassee NNootteess

Version 3.3  is a  major release,  changing many  things internally  and
externally.   The highlights are a  complete redesign of the  high-level
I/O system, which is  now based on explicit streams rather  then current
input/output.  The  old Edinburgh predicates (see/1, tell/1, etc.)   are
now defined on top of this layer instead of the other  way around.  This
fixes various internal problems and removes Prolog limits  on the number
of streams.

Much  progress  has been  made  to  improve ISO  compliance:    handling
strings  as  lists  of  one-character  atoms  is   now  supported  (next
to  character   codes  as  integers).      Many  more  exceptions   have
been  added and  printing  of exceptions  and messages  is  rationalised
using   Quintus   and   SICStus   Prolog   compatible   print_message/2,
message_hook/3 and print_message_lines/3.   All predicates described  in
[Deransart _e_t _a_l_., 1996] are now implemented.

As of version  3.3, SWI-Prolog adheres the  ISO _l_o_g_i_c_a_l _u_p_d_a_t_e _v_i_e_w  for
dynamic predicates.  See section 4.13.1 for details.

SWI-Prolog  3.3  includes garbage  collection  on  atoms,  removing  the
last serious memory  leak especially in text-manipulation  applications.
See  section 9.6.2.1.    In addition,  both the  user-level and  foreign
interface supports atoms holding _0_-_b_y_t_e_s.

Finally, an  alpha version of a  multi-threaded SWI-Prolog for Linux  is
added.    This version  is still  much slower  than the  single-threaded
version due  to frequent access to  `thread-local-data' as well as  some
too detailed  mutex locks.   The basic thread  API is ready for  serious
use and testing however.  See section 8.


11..66..1111..11 IInnccoommppaattiibbllee cchhaannggeess

A number  of incompatible changes  result from this upgrade.   They  are
all easily fixed however.

  o !/0_, call/1
    The  cut now behaves  according to the ISO  standard.  This  implies
    it  works in compound  goals passed  to call/1 and  is local to  the
    _c_o_n_d_i_t_i_o_n part of if-then-else as well as the argument of \+/1.

  o _a_t_o_m___c_h_a_r_s_/_2
    This  predicate  is now  ISO  compliant and  thus generates  a  list
    of  one-character atoms.    The behaviour  of the  old predicate  is
    available  in the  ---also ISO compliant---  atom_codes/2 predicate.
    Safest  repair is a  replacement of all  atom_chars  into atom_codes.
    If you do not want to change any source-code, you might want to use

    user:goal_expansion(atom_chars(A,B), atom_codes(A,B)).

  o _n_u_m_b_e_r___c_h_a_r_s_/_2
    Same applies for number_chars/2 and number_codes/2.

  o feature/2_, set_feature/2
    These  are replaced by  the ISO  compliant current_prolog_flag/2 and
    set_prolog_flag/2.   The library  backcomp provides definitions  for
    these predicates, so no source mmuusstt be updated.

  o _A_c_c_e_s_s_i_n_g _c_o_m_m_a_n_d_-_l_i_n_e _a_r_g_u_m_e_n_t_s
    This  used  to   be  provided  by  the  undocumented  '$argv'/1  and
    Quintus  compatible library unix/1.   Now  there is also  documented
    current_prolog_flag(_a_r_g_v_, _A_r_g_v).

  o _d_u_p___s_t_r_e_a_m_/_2
    Has  been deleted.   New  stream-aliases can deal  with most of  the
    problems  for which  dup_stream/2 was  designed and  dup/2 from  the
    _c_l_i_b package can with most others.

  o _o_p_/_3
    Operators  are now llooccaall ttoo mmoodduulleess.  This implies  any modification
    of  the operator-table does  not influence other  modules.  This  is
    consistent  with the proposed ISO behaviour and a necessity  to have
    any usable handling of operators in a multi-threaded environment.

  o _s_e_t___p_r_o_l_o_g___f_l_a_g_(_c_h_a_r_a_c_t_e_r___e_s_c_a_p_e_s_, _B_o_o_l_)
    This  Prolog flag is now an interface to changing attributes  on the
    current source-module,  effectively making this flag module-local as
    well.   This is required for consistent handling of  sources written
    with  ISO (obligatory) character-escape sequences together  with old
    Edinburgh code.

  o _c_u_r_r_e_n_t___s_t_r_e_a_m_/_3 _a_n_d _s_t_r_e_a_m___p_o_s_i_t_i_o_n
    These predicates have been moved to quintus.


11..66..1122 VVeerrssiioonn 33..44 RReelleeaassee NNootteess

The  3.4 release  is  a consolidation  release.    It  consolidates  the
improvements  and  standard conformance  of  the  3.3 releases.     This
version  is closely  compatible  with the  3.3  version except  for  one
important change:

  o _A_r_g_u_m_e_n_t _o_r_d_e_r _i_n select/3
    The  list-processing  predicate select/3  somehow  got into  a  very
    early  version of SWI-Prolog  with the wrong  argument order.   This
    has been fixed in  3.4.0.  The correct order is select(?Elem, ?List,
    ?Rest).

    As  select/3 has  no error  conditions, runtime  checking cannot  be
    done.   To simplify  debugging, the library module checkselect  will
    print  references to  select/3  in your  source code  and install  a
    version  of select that enters the debugger if select is  called and
    the second argument is not a list.

    This   library   can    be   loaded   explicitly   or   by   calling
    check_old_select/0.


11..66..1133 VVeerrssiioonn 44..00 RReelleeaassee NNootteess

As of  version 4.0 the  standard distribution  of SWI-Prolog is  bundled
with a  number of its  popular extension packages,  among which the  now
open source XPCE GUI toolkit (see section 1.5).   No significant changes
have been made to the basic SWI-Prolog engine.

Some useful tricks in the integrated environment:

  o _R_e_g_i_s_t_e_r _t_h_e _G_U_I _t_r_a_c_e_r
    Using  a call to guitracer/0,  hooks are installed that replace  the
    normal command-line driven tracer with a graphical front-end.

  o _R_e_g_i_s_t_e_r _P_c_e_E_m_a_c_s _f_o_r _e_d_i_t_i_n_g _f_i_l_e_s
    From  your initialisation file.  you  can load emacs/swi_prolog that
    cause edit/1 to use the built-in PceEmacs editor.


11..66..1144 VVeerrssiioonn 55..00 RReelleeaassee NNootteess

Version  5.0 marks  a breakpoint  in  the philosophy,  where  SWI-Prolog
moves  from  a  dual GPL/proprietary  to  a  uniform  LGPL  (Lesser  GNU
Public Licence)  schema, providing  a widely usable  Free Source  Prolog
implementation.

On  the  technical  site  the  development  environment,  consisting  of
source-level  debugger,  integrated  editor  and  various  analysis  and
navigation tools progress steadily towards a mature set of tools.

Many portability issues have been improved, including a  port to MacOS X
(Darwin).

For details, please visit the new website at http://www.swi-prolog.org


11..66..1155 VVeerrssiioonn 55..11 RReelleeaassee NNootteess

Version 5.1 is  a beta-serie introducing portable multi-threading.   See
chapter 8.   In  addition it introduces many  new facilities to  support
server applications,  such as  the new  rlimit library  to limit  system
resources and the possibility to set timeouts on input streams.


11..66..1166 VVeerrssiioonn 55..22 RReelleeaassee NNootteess

Version  5.2  consolidates   the  5.1.x  beta  series  that   introduced
threading and many related modifications to the kernel.


11..66..1177 VVeerrssiioonn 55..33 RReelleeaassee NNootteess

Version  5.3.x   is  a  development   series  for  adding   coroutining,
constraints, global variables,  cyclic terms (infinite trees) and  other
goodies  to the  kernel.   The  package JPL,  providing a  bidirectional
Java/Prolog  interface is  added to  the common  source-tree and  common
binary packages.


11..66..1188 VVeerrssiioonn 55..44 RReelleeaassee NNootteess

Version 5.4 consolidates the 5.3.x beta series.


11..66..1199 VVeerrssiioonn 55..55 RReelleeaassee NNootteess

Version  5.5.x provides  support  for  _w_i_d_e _c_h_a_r_a_c_t_e_r_s  with  UTF-8  and
UNICODE I/O  (section 2.17.1).   On both 32  and 64-bit hardware  Prolog
integers are now at  minimum 64-bit integers.  If available,  SWI-Prolog
arithmetic  uses the  GNU  GMP  library to  provided  _u_n_b_o_u_n_d_e_d  integer
arithmetic  as well  as rational  arithmetic.    Adding GMP  support  is
sponsored  by Scientific  Software and  Systems Limited,  www.sss.co.nz.
This version also incorporates clp(r) by Christian  Holzbaur, brought to
SWI-Prolog by Tom Schrijvers and Leslie De Koninck (section 11.8).


11..66..2200 VVeerrssiioonn 55..66 RReelleeaassee NNootteess

Version 5.6 consolidates the 5.5.x beta series.


11..77 DDoonnaattee ttoo tthhee SSWWII--PPrroolloogg pprroojjeecctt

If you  are happy with  SWI-Prolog, you  care it to  be around for  much
longer while it becomes  faster, more stable and with more  features you
should consider to  donate to the SWI-Prolog  foundation.  Please  visit
the page below.

    http://www.swi-prolog.org/donate.html


11..88 AAcckknnoowwlleeddggeemmeennttss

Some small parts of the Prolog code of SWI-Prolog  are modified versions
of the corresponding Edinburgh C-Prolog code:   grammar rule compilation
and  writef/2.    Also some  of  the  C-code originates  from  C-Prolog:
finding the  path of the  currently running executable  and some of  the
code underlying  absolute_file_name/2.   Ideas  on programming style  and
techniques originate from  C-Prolog and Richard O'Keefe's _t_h_i_e_f  editor.
An  important  source  of inspiration  are  the  programming  techniques
introduced by Anjo Anjewierden in PCE version 1 and 2.

I also  would like to thank  those who had the  fade of using the  early
versions of this system,  suggested extensions or reported bugs.   Among
them are Anjo Anjewierden, Huub Knops, Bob  Wielinga, Wouter Jansweijer,
Luc Peerdeman, Eric Nombden, Frank van Harmelen, Bert Rengel.

Martin Jansche  (jansche@novell1.gs.uni-heidelberg.de) has been so  kind
to reorganise the sources for version 2.1.3 of this manual.

Horst  von Brand  has been  so  kind to  fix many  typos  in the  2.7.14
manual.  Thanks!

Bart  Demoen and  Tom  Schrijvers  have helped  me  adding  coroutining,
constraints,  global  variables and  support  for  cyclic terms  to  the
kernel.   Tom has provided the  integer interval constraint solver,  the
CHR compiler and some of the coroutining predicates.

Paul Singleton has integrated Fred Dushin's  Java-calls-Prolog side with
his Prolog-calls-Java side into the current  bidirectional JPL interface
package.

Richard O'Keefe  is gratefully acknowledged for  his efforts to  educate
beginners as well as valuable comments on proposed new developments.

Scientific  Software and  Systems Limited,  www.sss.co.nz has  sponsored
the development  if the  SSL library  as well as  unbounded integer  and
rational number arithmetic.

Leslie de Koninck has made clp(QR) available to SWI-Prolog.

Markus Triska has contributed to various libraries.

Paulo  Moura's  great   experience  in  maintaining  Logtalk  for   many
Prolog systems  including SWI-Prolog  has helped in  many places  fixing
compatibility issues.   He also worked on the MacOS port and  fixed many
typos in the 5.6.9 release of the documentation.


CChhaapptteerr 22..  OOVVEERRVVIIEEWW


22..11 GGeettttiinngg ssttaarrtteedd qquuiicckkllyy


22..11..11 SSttaarrttiinngg SSWWII--PPrroolloogg


22..11..11..11 SSttaarrttiinngg SSWWII--PPrroolloogg oonn UUnniixx

By default, SWI-Prolog is installed as `pl',  though some administrators
call  it  `swipl'  or `swi-prolog'.     The  command-line  arguments  of
SWI-Prolog  itself  and  its  utility  programs   are  documented  using
standard  Unix  man pages.     SWI-Prolog  is normally  operated  as  an
interactive application simply by starting the program:

machine% pl
Welcome to SWI-Prolog (Version 5.6.42)
Copyright (c) 1990-2007 University of Amsterdam.
SWI-Prolog comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to redistribute it under certain conditions.
Please visit http://www.swi-prolog.org for details.

For help, use ?- help(Topic). or ?- apropos(Word).

1 ?-

After  starting Prolog,  one  normally loads  a  program into  it  using
consult/1, which  --- for historical reasons  --- may be abbreviated  by
putting the  name of  the program  file between  square brackets.    The
following  goal loads  the  file  likes.pl containing  clauses  for  the
predicates likes/2:

?- [likes].
% likes compiled, 0.00 sec, 596 bytes.

Yes
?-

After this  point, Unix  and Windows users  unite, so  if you are  using
Unix please continue at section 2.1.2.


22..11..11..22 SSttaarrttiinngg SSWWII--PPrroolloogg oonn WWiinnddoowwss

After SWI-Prolog has been  installed on a Windows system,  the following
important new things are available to the user:

  o A  folder  (called  _d_i_r_e_c_t_o_r_y in  the  remainder of  this  document)
    called  pl  containing the  executables,  libraries, etc.    of  the
    system.  No files are installed outside this directory.

  o A  program  plwin.exe,  providing  a  window  for  interaction  with
    Prolog.  The  program plcon.exe is a version of SWI-Prolog that runs
    in a DOS-box.

  o The  file-extension .pl  is associated with  the program  plwin.exe.
    Opening  a .pl file will cause plwin.exe to start,  change directory
    to  the directory in  which the file-to-open  resides and load  this
    file.

The  normal   way  to  start  with   the  likes.pl  file  mentioned   in
section 2.1.1.1  is by simply double-clicking  this file in the  Windows
explorer.


22..11..22 EExxeeccuuttiinngg aa qquueerryy

After loading a program,  one can ask Prolog queries about  the program.
The query below asks Prolog what food `sam' likes.   The system responds
with X = <_v_a_l_u_e> if it can prove the goal for a certain _X. The  user can
type the semi-colon  (;) if (s)he wants  another solution, or return  if
(s)he is satisfied, after which Prolog will say YYeess.   If Prolog answers
NNoo,  it  indicates it  cannot  find any  (more)  answers to  the  query.
Finally, Prolog can answer using an error message  to indicate the query
or program contains an error.

?- likes(sam, X).

X = dahl ;

X = tandoori ;

...

X = chips ;

No
?-


22..22 TThhee uusseerr''ss iinniittiiaalliissaattiioonn ffiillee

After  the necessary  system  initialisation  the system  consults  (see
consult/1) the user's startup file.  The base-name  of this file follows
conventions of  the operating  system.   On MS-Windows,  it is the  file
pl.ini  and on  Unix systems  .plrc.   The  file is  searched using  the
file_search_path/2 clauses for user_profile.  The table below  shows the
default value for this search-path.   The phrase <_a_p_p_d_a_t_a> refers to the
Windows CSIDL  name for  the folder.   The  actual name  depends on  the
Windows language.  English versions typically use ApplicationData.   See
also win_folder/2

                   ___________________________________
                   |______________|UUnniixx__||WWiinnddoowwss__________________________||
                   || llooccaall ||.    |.                   |
                   |_hhoommee__||~____|<_a_p_p_d_a_t_a>/SWI-Prolog_|

After the  first startup  file is found  it is  loaded and Prolog  stops
looking for further startup files.  The name of the  startup file can be
changed with the  `-f file' option.   If _F_i_l_e denotes an absolute  path,
this file is loaded,  otherwise the file is searched for using  the same
conventions as for the default startup file.  Finally,  if _f_i_l_e is none,
no file is loaded.

See  also  the  -s  (script)  and  -F  (system-wide  initialisation)  in
section 2.4 and section 2.3.


22..33 IInniittiiaalliissaattiioonn ffiilleess aanndd ggooaallss

Using  command-line  arguments (see  section  2.4),  SWI-Prolog  can  be
forced to  load files  and execute queries  for initialisation  purposes
or  non-interactive operation.    The  most  commonly used  options  are
-f file or  -s file to  make Prolog load  a file,  -g goal to define  an
initialisation  goal and  -t goal to  define the  _t_o_p_-_l_e_v_e_l _g_o_a_l.    The
following  is a  typical example  for starting  an application  directly
from the command-line.

machine% pl -s load.pl -g go -t halt

It  tells  SWI-Prolog to  load  load.pl,  start  the  application  using
the  _e_n_t_r_y_-_p_o_i_n_t  go/0  and  ---instead  of   entering  the  interactive
top-level---  exit after  completing  go/0.    The  -q  may be  used  to
suppress all informational messages.

In  MS-Windows,  the  same  can  be  achieved  using  a  short-cut  with
appropriately  defined  command-line  arguments.      A  typically  seen
alternative  is to  write  a file  run.pl  with content  as  illustrated
below.  Double-clicking run.pl will start the application.

:- [load].                      % load program
:- go.                          % run it
:- halt.                        % and exit

Section  2.10.2.1 discusses  further scripting  options  and chapter  10
discusses the  generation of runtime executables.   Runtime  executables
are  a mean  to  deliver executables  that  do  not require  the  Prolog
system.


22..44 CCoommmmaanndd--lliinnee ooppttiioonnss

The full set of command-line options is given below:

----hheellpp
    When  given as  the only  option, it summarises  the most  important
    options.  Also available as -h and -help.

----vveerrssiioonn
    When  given as the  only option, it  summarises the version and  the
    architecture identifier.  Also available as -v.

----aarrcchh
    When   given  as  the  only  option,  it  prints   the  architecture
    identifier   (see  Prolog  flag   arch)  and  exits.      See   also
    -dump-runtime-variables.  Also available as -arch.

----dduummpp--rruunnttiimmee--vvaarriiaabblleess
    When  given as  the only option,  it prints  a sequence of  variable
    settings  that can  be  used in  shell-scripts to  deal with  Prolog
    parameters.   This feature is  also used by plld (see section  9.7).
    Below  is a typical example of  using this feature.  Also  available
    as -dump-runtime-variables.

    eval `pl --dump-runtime-variables`
    cc -I$PLBASE/include -L$PLBASE/runtime/$PLARCH ...

    The  option can be  followed by  =sh to dump  in POSIX shell  format
    (default) or cmd to dump in MS-Windows cmd.exe compatible format.

----wwiinn__aapppp
    This  option  is  available  only  in  plwin.exe  and  is  used  for
    the   start-menu  item.      If  causes   plwin  to  start  in   the
    folder  ...\My Documents\Prolog  or  local equivalent  thereof  (see
    win_folder/2).   The Prolog subdirectory  is created if it does  not
    exist.

----qquuiieett
    Set  the Prolog  flag verbose to  silent, suppressing  informational
    and banner messages.  Also available as -q.

--LL_s_i_z_e_[_k_m_g_]
    Give  local stack limit (default 16Mb  on 32-bit and 32Mb on  64-bit
    hardware).   Note  that there  is no space  between the size  option
    and  its  argument.   By  default, the  argument  is interpreted  in
    Kbytes.   Postfix the  argument with m for  Mbytes or g for  Gbytes.
    The following example specifies 64 Mbytes local stack.

    % pl -L64m

    A maximum is  useful to stop buggy programs from claiming all memory
    resources.   -L0 sets the limit to the highest possible value.   See
    section 2.18.

--GG_s_i_z_e_[_k_m_g_]
    Give  global  stack limit  (4 Mbytes  default).    See -L  for  more
    details.

--TT_s_i_z_e_[_k_m_g_]
    Give  trail  stack  limit  (4  Mbytes  default).     This  limit  is
    relatively  high because trail-stack overflows are not  often caused
    by program bugs.  See -L for more details.

--AA_s_i_z_e_[_k_m_g_]
    Give  argument stack limit (1 Mbytes  default).  The argument  stack
    limits  the  maximum  nesting of  terms  that  can be  compiled  and
    executed.    SWI-Prolog does `last-argument  optimisation' to  avoid
    many  deeply nested  structure  using this  stack.   Enlarging  this
    limit is only necessary in extreme cases.  See -L for more details.

--cc _f_i_l_e _._._.
    Compile files into an `intermediate code file'.  See section 2.10.

--oo _o_u_t_p_u_t
    Used  in combination  with -c  or -b  to determine  output file  for
    compilation.

--OO
    Optimised  compilation.  See current_prolog_flag/2flag  optimise for
    details.

----nnooddeebbuugg
    Disable   debugging.        See   the   current_prolog_flag/2   flag
    generate_debug_info for details.

--ss _f_i_l_e
    Use  _f_i_l_e as a  script-file.   The script file  is loaded after  the
    initialisation  file  specified with  the -f file  option.    Unlike
    -f file,  using -s does  not stop Prolog  from loading the  personal
    initialisation file.

--ff _f_i_l_e
    Use _f_i_l_e as  initialisation file instead of the default .plrc (Unix)
    or pl.ini (Windows).   `-f none' stops SWI-Prolog from searching for
    a  startup file.    This option  can be  used as  an alternative  to
    -s file  that stops Prolog from loading the  personal initialisation
    file.  See also section 2.2.

--FF _s_c_r_i_p_t
    Selects  a startup-script from the  SWI-Prolog home directory.   The
    script-file  is  named <_s_c_r_i_p_t>.rc.    The  default _s_c_r_i_p_t  name  is
    deduced  from  the  executable,  taking the  leading  alphanumerical
    characters  (letters, digits and underscore) from  the program-name.
    -F none stops looking  for a script.  Intended for simple management
    of  slightly  different  versions.    One  could for  example  write
    a  script  iso.rc  and  then select  ISO  compatibility  mode  using
    pl -F iso or make a link from iso-pl to pl.

--gg _g_o_a_l
    _G_o_a_l  is executed just before entering the top level.  Default  is a
    predicate  which prints the  welcome message.   The welcome  message
    can  thus be suppressed by  giving -g true.   _g_o_a_l can be a  complex
    term.    In  this case  quotes  are normally  needed to  protect  it
    from  being  expanded by  the shell.    A  save way  to  run a  goal
    non-interactively is here:

    % pl <options> -g go,halt -t 'halt(1)'

--tt _g_o_a_l
    Use  _g_o_a_l  as  interactive top-level  instead  of the  default  goal
    prolog/0.    _g_o_a_l can  be a  complex term.   If  the top-level  goal
    succeeds  SWI-Prolog exits  with status  0.   If it  fails the  exit
    status  is 1.  If the toplevel raises an exception, this  is printed
    as an uncaught error  and the toplevel is restarted.  This flag also
    determines the goal started  by break/0 and abort/0.  If you want to
    stop  the user from entering interactive mode start  the application
    with `-g goal' and give `halt' as top-level.

--ttttyy
    Unix  only.      Switches  controlling  the  terminal  for  allowing
    single-character  commands to the tracer and  get_single_char/1.   By
    default  manipulating  the terminal  is  enabled unless  the  system
    detects  it is not  connected to a  terminal or it  is running as  a
    GNU-Emacs  inferior process.   This flag  is sometimes required  for
    smooth interaction with other applications.

----nnoossiiggnnaallss
    Inhibit any signal  handling by Prolog, a property that is sometimes
    desirable  for embedded  applications.   This option  sets the  flag
    signals to false.  See section 9.6.20.1 for details.

----hhoommee==DDIIRR
    Use DIR as home directory.  See section 9.8 for details.

--xx _b_o_o_t_f_i_l_e
    Boot  from _b_o_o_t_f_i_l_e instead  of the system's default  boot file.   A
    bootfile is a  file resulting from a Prolog compilation using the -b
    or -c option or a program saved using qsave_program/[1,2].

--pp _a_l_i_a_s_=_p_a_t_h_1_[_:_p_a_t_h_2 _._._._]
    Define  a path alias for file_search_path.  _a_l_i_a_s is the name  of the
    alias,  _p_a_t_h_1 _._._.  is  a list of values for  the alias.  On  Windows
    the  list-separator is ;.   On other  systems it is :.   A value  is
    either  a term of the form  alias(value) or pathname.  The  computed
    aliases  are added  to file_search_path/2 using  asserta/1, so  they
    precede  predefined values  for the  alias.   See file_search_path/2
    for details on using this file-location mechanism.

--
    Stops  scanning for more  arguments, so you  can pass arguments  for
    your  application after this  one.   See current_prolog_flag/2 using
    the flag argv for obtaining the command-line arguments.

The following options  are for system maintenance.   They are given  for
reference only.

--bb _i_n_i_t_f_i_l_e _._._.-c _f_i_l_e _._._.
    Boot  compilation.   _i_n_i_t_f_i_l_e  _._._.   are compiled  by the  C-written
    bootstrap  compiler,  _f_i_l_e  _._._.    by  the normal  Prolog  compiler.
    System maintenance only.

--dd _l_e_v_e_l
    Set  debug  level to  _l_e_v_e_l.    Only  has effect  if the  system  is
    compiled with the -DO_DEBUG flag.  System maintenance only.


22..55 GGNNUU EEmmaaccss IInntteerrffaaccee

The default  Prolog mode for  GNU-Emacs can be  activated by adding  the
following rules to your Emacs initialisation file:

(setq auto-mode-alist
      (append
       '(("\\.pl" . prolog-mode))
       auto-mode-alist))
(setq prolog-program-name "pl")
(setq prolog-consult-string "[user].\n")
;If you want this.  Indentation is either poor or I don't use
;it as intended.
;(setq prolog-indent-width 8)

Unfortunately the  default Prolog mode  of GNU-Emacs  is not very  good.
An  alternative  prolog.el  file for  GNU-Emacs  20  is  available  from
http://www.freesoft.cz/ pdm/software/emacs/prolog-mode/  and  for   GNU-
Emacs 19 from http://w1.858.telia.com/ u85810764/Prolog-mode/index.html


22..66 OOnnlliinnee HHeellpp

Online  help  provides a  fast  lookup  and browsing  facility  to  this
manual.   The online  manual can show predicate  definitions as well  as
entire sections of the manual.

The online help  is displayed from the  file 'MANUAL'. The file  helpidx
provides  an index  into  this  file.    'MANUAL'  is created  from  the
LaTeX sources  with a modified version  of dvitty, using overstrike  for
printing bold  text and  underlining for  rendering italic text.    XPCE
is shipped  with swi_help,  presenting the information  from the  online
help in a hypertext  window.  The Prolog flag  write_help_with_overstrike
controls whether  or not help/1  writes its  output using overstrike  to
realise bold  and underlined  output or  not.   If this  Prolog flag  is
not  set it  is initialised  by the  help library  to true  if the  TERM
variable equals  xterm and false  otherwise.  If  this default does  not
satisfy you, add the  following line to your personal startup  file (see
section 2.2):

:- set_prolog_flag(write_help_with_overstrike, true).


hheellpp
    Equivalent to help(help/1).


hheellpp((_+_W_h_a_t))
    Show specified part of the manual.  _W_h_a_t is one of:

          <Name>/<_A_r_i_t_y> Give help on specified predicate
          <Name>         Give  help  on named  predicate  with any
                         arity  or C interface  function with that
                         name
          <Section>      Display  specified   section.     Section
                         numbers are  dash-separated numbers:  2-3
                         refers  to  section  2.3  of the  manual.

                         Section   numbers   are  obtained   using
                         apropos/1.

    Examples:

       ?- help(assert).     Give help on predicate assert
       ?- help(3-4).        Display section 3.4 of the manual
       ?- help('PL_retry'). Give    help   on    interface   function
                            PL_retry()

    See also apropos/1,  and the SWI-Prolog home page at http://www.swi-
    prolog.org,  which provides  a FAQ,  an HTML version  of manual  for
    online browsing and HTML and PDF versions for downloading.


aapprrooppooss((_+_P_a_t_t_e_r_n))
    Display all predicates,  functions and sections that have _P_a_t_t_e_r_n in
    their  name or summary  description.   Lowercase letters in  _P_a_t_t_e_r_n
    also match a corresponding uppercase letter.  Example:

        ?- apropos(file).  Display  predicates,  functions and  sec-
                           tions that have  `file' (or `File', etc.)
                           in their summary description.


eexxppllaaiinn((_+_T_o_E_x_p_l_a_i_n))
    Give an explanation on  the given `object'.  The argument may be any
    Prolog  data object.   If  the argument is  an atom,  a term of  the
    form  _N_a_m_e_/_A_r_i_t_y or a term of the form  _M_o_d_u_l_e_:_N_a_m_e_/_A_r_i_t_y, explain/1
    describes  the predicate as well as possible references to it.   See
    also gxref/0.


eexxppllaaiinn((_+_T_o_E_x_p_l_a_i_n_, _-_E_x_p_l_a_n_a_t_i_o_n))
    Unify  _E_x_p_l_a_n_a_t_i_o_n with an explanation for _T_o_E_x_p_l_a_i_n.   Backtracking
    yields further explanations.


22..77 CCoommmmaanndd--lliinnee hhiissttoorryy

SWI-Prolog offers a query substitution mechanism called `history'.   The
availability of  this feature is controlled  by set_prolog_flag/2,  using
the  history Prolog  flag.   By  default,  history is  available if  the
Prolog flag  readline is  false.   To enable  this feature,  remembering
the last  50 commands,  put the  following into your  startup file  (see
section 2.2):

:- set_prolog_flag(history, 50).

The history  system allows the  user to compose  new queries from  those
typed  before and  remembered by  the  system.   The  available  history
commands are  shown in  table 2.1.   History  expansion is  not done  if
these sequences appear in quoted atoms or strings.
             ______________________________________________
             | !!.   |Repeat last query                     |

             | !nr.  |Repeat query numbered <_n_r>            |
             | !str. |Repeat last query starting with <_s_t_r> |
             | h.    |Show history of commands              |
             |_!h.___|Show_this_list_______________________ |

                      Table 2.1:  History commands


22..88 RReeuussee ooff ttoopp--lleevveell bbiinnddiinnggss

Bindings resulting  from the  successful execution of  a top-level  goal
are asserted  in a  database.   These values  may be  reused in  further
top-level  queries as  $Var.    Only the  latest binding  is  available.
Example:
1 ?- maplist(plus(1), "hello", X).

X = [105,102,109,109,112]

Yes
2 ?- format('~s~n', [$X]).
ifmmp

Yes

3 ?-

                Figure 2.1:  Reusing top-level bindings

Note that variables may be set by executing =/2:

6 ?- X = statistics.

X = statistics

Yes
7 ?- $X.
28.00 seconds cpu time for 183,128 inferences
4,016 atoms, 1,904 functors, 2,042 predicates, 52 modules
55,915 byte codes; 11,239 external references

                      Limit    Allocated       In use
Heap         :                                624,820 Bytes
Local  stack :    2,048,000        8,192          404 Bytes
Global stack :    4,096,000       16,384          968 Bytes
Trail  stack :    4,096,000        8,192          432 Bytes

Yes
8 ?-


22..99 OOvveerrvviieeww ooff tthhee DDeebbuuggggeerr

SWI-Prolog has a 6-port  tracer, extending the standard 4-port  Byrd box
model tracer  [Byrd, 1980, Clocksin & Melish, 1987] with two  additional
ports.   The optional _u_n_i_f_y port allows  the user to inspect the  result
after unification  of the  head.   The _e_x_c_e_p_t_i_o_n  port shows  exceptions
raised by throw/1 or one of the built-in predicates.  See section 4.9.

The standard  ports are called call,  exit, redo, fail  and unify.   The
tracer is started  by the trace/0 command,  when a spy point is  reached
and the system is  in debugging mode (see spy/1 and debug/0) or  when an
exception is raised.

The interactive top-level  goal trace/0 means ``trace the next  query''.
The tracer shows the  port, displaying the port name, the  current depth
of the  recursion and the goal.   The goal  is printed using the  Prolog
predicate  write_term/2.     The style  is  defined  by the  Prolog  flag
debugger_print_options and can be modified using this flag or  using the
w, p and d commands of the tracer.
1 ?- visible(+all), leash(-exit).

Yes
2 ?- trace, min([3, 2], X).
  Call:  ( 3) min([3, 2], G235) ? creep
  Unify: ( 3) min([3, 2], G235)
  Call:  ( 4) min([2], G244) ? creep
  Unify: ( 4) min([2], 2)
  Exit:  ( 4) min([2], 2)

  Call:  ( 4) min(3, 2, G235) ? creep
  Unify: ( 4) min(3, 2, G235)
  Call:  ( 5) 3 < 2 ? creep
  Fail:  ( 5) 3 < 2 ? creep
  Redo:  ( 4) min(3, 2, G235) ? creep
  Exit:  ( 4) min(3, 2, 2)
  Exit:  ( 3) min([3, 2], 2)

Yes
[trace] 3 ?-

                       Figure 2.2:  Example trace

On _l_e_a_s_h_e_d  _p_o_r_t_s (set  with the  predicate leash/1,  default are  call,
exit, redo and  fail) the user is prompted  for an action.  All  actions
are single character  commands which are executed wwiitthhoouutt waiting  for a
return, unless the command-line option -tty is active.  Tracer options:

+ ((SSppyy))
    Set a spy point (see spy/1) on the current predicate.

- ((NNoo ssppyy))
    Remove the spy point (see nospy/1) from the current predicate.

/ ((FFiinndd))
    Search  for a port.   After the  `/', the user  can enter a line  to
    specify  the port to  search for.   This line consists  of a set  of
    letters  indicating the  port type,  followed by  an optional  term,
    that  should unify with  the goal run by  the port.   If no term  is
    specified  it is taken as a variable, searching for any port  of the
    specified  type.  If an atom is given, any goal whose  functor has a
    name equal to that atom matches.  Examples:

            /f               Search for any fail port

            /fe solve        Search for a  fail or exit  port of
                             any goal with name solve
            /c solve(a, _)   Search for a call to  solve/2 whose
                             first argument is a variable or the
                             atom a
            /a member(_, _)  Search for  any  port on  member/2.
                             This is equivalent to setting a spy
                             point on member/2.

. ((RReeppeeaatt ffiinndd))
    Repeat the last find command (see `/').

A ((AAlltteerrnnaattiivveess))
    Show all goals that have alternatives.

C ((CCoonntteexxtt))
    Toggle  `Show Context'.   If on, the context  module of the goal  is
    displayed between square brackets (see section 5).  Default is off.

L ((LLiissttiinngg))
    List the current predicate with listing/1.

a ((AAbboorrtt))
    Abort Prolog execution (see abort/0).

b ((BBrreeaakk))
    Enter a Prolog break environment (see break/0).

c ((CCrreeeepp))
    Continue execution, stop at next port.  (Also return, space).

d ((DDiissppllaayy))
    Set  the max_depth(_D_e_p_t_h) option of debugger_print_options,  limiting
    the  depth  to which  terms are  printed.    See also  the  w and  p
    options.

e ((EExxiitt))
    Terminate Prolog (see halt/0).

f ((FFaaiill))
    Force failure of the current goal.

g ((GGooaallss))
    Show the list of  parent goals (the execution stack).  Note that due
    to  tail recursion optimization a  number of parent goals might  not
    exist any more.

h ((HHeellpp))
    Show available options (also `?').

i ((IIggnnoorree))
    Ignore the current goal, pretending it succeeded.

l ((LLeeaapp))
    Continue execution, stop at next spy point.

n ((NNoo ddeebbuugg))
    Continue execution in `no debug' mode.

p ((PPrriinntt))
    Set  the Prolog  flag debugger_print_options to  [quoted(true), por-
    tray(true), max_depth(10), priority(699)].  This is the default.

r ((RReettrryy))
    Undo  all actions (except for database and i/o actions) back  to the
    call  port of  the current  goal and  resume execution  at the  call
    port.

s ((SSkkiipp))
    Continue  execution,  stop  at the  next  port  of tthhiiss  goal  (thus
    skipping all calls to children of this goal).

u ((UUpp))
    Continue  execution, stop at the next port of tthhee ppaarreenntt  goal (thus
    skipping  this goal and all calls to  children of this goal).   This
    option is useful to stop tracing a failure driven loop.

w ((WWrriittee))
    Set      the      Prolog     flag      debugger_print_options     to
    [quoted(true), attributes(write), priority(699)],          bypassing
    portray/1, etc.

The  ideal 4  port Byrd  box  model [Byrd, 1980]  as described  in  many
Prolog books  [Clocksin & Melish, 1987] is  not visible  in many  Prolog
implementations because  code optimisation removes  part of the  choice-
and exit-points.    Backtrack points are  not shown  if either the  goal
succeeded  deterministically  or its  alternatives  were  removed  using
the  cut.    When running  in debug  mode  (debug/0) choice  points  are
only  destroyed when  removed by  the cut.    In debug  mode, last  call
optimisation is switched off.

Reference information to  all predicates available for manipulating  the
debugger is in section 4.38.


22..1100 CCoommppiillaattiioonn


22..1100..11 DDuurriinngg pprrooggrraamm ddeevveellooppmmeenntt

During  program   development,  programs   are  normally  loaded   using
consult/1, or the list abbreviation.  It is  common practice to organise
a project  as a  collection of source  files and a  _l_o_a_d_-_f_i_l_e, a  Prolog
file  containing only  use_module/[1,2]  or ensure_loaded/1  directives,
possibly  with a  definition  of the  _e_n_t_r_y_-_p_o_i_n_t  of the  program,  the
predicate that  is normally used  to start  the program.   This file  is
often  called load.pl.    If the  entry-point is  called _g_o,  a  typical
session starts as:

% pl
<banner>

1 ?- [load].
<compilation messages>

Yes
2 ?- go.
<program interaction>

When  using  Windows,  the  user  may  open  load.pl  from  the  Windows
explorer,  which will cause  plwin.exe to  be started  in the  directory
holding load.pl.  Prolog loads load.pl before entering the top-level.


22..1100..22 FFoorr rruunnnniinngg tthhee rreessuulltt

There are  various options if  you want to make  your program ready  for
real usage.   The best  choice depends on whether  the program is to  be
used only  on machines  holding the SWI-Prolog  development system,  the
size of the program and the operating system (Unix vs. Windows).


22..1100..22..11 UUssiinngg PPrroollooggSSccrriipptt

New in  version 4.0.5  is the possibility  to use  a Prolog source  file
directly  as a  Unix  script-file.   The  same  mechanism is  useful  to
specify additional parameters for running a Prolog file on Windows.

If the  first letter of a  Prolog file is #,  the first line is  treated
as comment.  To  create a Prolog script, make the first line  start like
this:

    #!/path/to/pl <_o_p_t_i_o_n_s> -s

Prolog recognises this  starting sequence and causes the interpreter  to
receive the following argument-list:

    /path/to/pl <_o_p_t_i_o_n_s> -s <_s_c_r_i_p_t> -- <_S_c_r_i_p_t_A_r_g_u_m_e_n_t_s>

Instead of  -s, the user may  use -f to stop  Prolog from looking for  a
personal initialisation file.

Here is a simple script doing expression evaluation:

#!/usr/bin/pl -q -t main -f

eval :-
        current_prolog_flag(argv, Argv),
        append(_, [--|Args], Argv),
        concat_atom(Args, ' ', SingleArg),
        term_to_atom(Term, SingleArg),
        Val is Term,
        format('~w~n', [Val]).

main :-
        catch(eval, E, (print_message(error, E), fail)),
        halt.
main :-
        halt(1).

And here are two example runs:

% eval 1+2
3
% eval foo
ERROR: Arithmetic: `foo/0' is not a function
%

TThhee  WWiinnddoowwss  vveerrssiioonn supports  the  #!  construct  too,   but  here  it
serves  a rather  different role.    The  Windows shell  already  allows
the  user to  start Prolog  source files  directly  through the  Windows
file-type  association.   Windows  however makes  it rather  complicated
to provide  additional parameters, such  as the required stack-size  for
an individual  Prolog file.   The #! line  provides for this,  providing
a  more flexible  approach  than changing  the  global  defaults.    The
following starts  Prolog with unlimited stack-size  on the given  source
file:

#!/usr/bin/pl -L0 -T0 -G0 -s

....

Note the  use of  /usr/bin/pl, which  specifies the interpreter.    This
argument is ignored in the Windows version, but  required to ensure best
cross-platform compatibility.


22..1100..22..22 CCrreeaattiinngg aa sshheellll--ssccrriipptt

With  the introduction  of _P_r_o_l_o_g_S_c_r_i_p_t  (see section  2.10.2.1),  using
shell-scripts  as explained  in this  section has  become redundant  for
most applications.

Especially  on  Unix systems  and  not-too-large  applications,  writing
a  shell-script  that  simply  loads  your  application  and  calls  the
entry-point is often a good choice.  A skeleton for  the script is given
below, followed by the Prolog code to obtain the program arguments.

#!/bin/sh

base=<absolute-path-to-source>
PL=pl

exec $PL -f none -g "load_files(['$base/load'],[silent(true)])" \
         -t go -- $*

go :-
        current_prolog_flag(argv, Arguments),
        append(_SytemArgs, [--|Args], Arguments), !,
        go(Args).

go(Args) :-
        ...

On Windows  systems, similar  behaviour can  be achieved  by creating  a
shortcut to Prolog, passing the proper options or writing a .bat file.


22..1100..22..33 CCrreeaattiinngg aa ssaavveedd--ssttaattee

For  larger programs,  as  well as  for programs  that are  required  to
run  on systems  that  do not  have  the SWI-Prolog  development  system
installed,  creating a  saved  state is  the  best solution.    A  saved
state is created using qsave_program/[1,2] or using the  linker plld(1).
A  saved state  is a  file  containing machine-independent  intermediate
code  in  a  format  dedicated  for  fast  loading.    Optionally,   the
emulator may be integrated  in the saved state, creating  a single-file,
but  machine-dependent,  executable.    This  process  is  described  in
chapter 10.


22..1100..22..44 CCoommppiillaattiioonn uussiinngg tthhee --cc ccoommmmaanndd--lliinnee ooppttiioonn

This mechanism loads a series of Prolog source files  and then creates a
saved-state as qsave_program/2 does.  The command syntax is:

% pl [option ...] [-o output] -c file ...

The  _o_p_t_i_o_n_s argument  are  options to  qsave_program/2 written  in  the
format below.    The option-names  and their values  are described  with
qsave_program/2.

    --_o_p_t_i_o_n_-_n_a_m_e=_o_p_t_i_o_n_-_v_a_l_u_e

For  example,  to  create  a  stand-alone   executable  that  starts  by
executing main/0  and for which  the source  is loaded through  load.pl,
use the command

% pl --goal=main --stand_alone=true -o myprog -c load.pl

This performs exactly the same as executing

% pl
<banner>
?- [load].
?- qsave_program(myprog,
                 [ goal(main),
                   stand_alone(true)
                 ]).
?- halt.


22..1111 EEnnvviirroonnmmeenntt CCoonnttrrooll ((PPrroolloogg ffllaaggss))

The  predicates  current_prolog_flag/2 and  set_prolog_flag/2 allow  the
user  to examine  and modify  the execution  environment.   It  provides
access  to whether  optional  features are  available on  this  version,
operating  system,  foreign-code  environment,  command-line  arguments,
version,  as well  as runtime  flags to  control  the runtime  behaviour
of  certain  predicates  to  achieve  compatibility  with  other  Prolog
environments.


ccuurrrreenntt__pprroolloogg__ffllaagg((_?_K_e_y_, _-_V_a_l_u_e))                                  _[_I_S_O_]
    The  predicate current_prolog_flag/2defines an interface  to instal-
    lation  features:  options  compiled in, version,  home, etc.   With
    both  arguments unbound, it will generate all defined  Prolog flags.
    With  the `Key'  instantiated  it unifies  the value  of the  Prolog
    flag.   Flag values  are typed.  Flags  marked as bool can have  the
    values  true and false.   Some Prolog flags  are not defined in  all
    versions, which is  normally indicated in the documentation below as
    _`_`_i_f  _p_r_e_s_e_n_t _a_n_d _t_r_u_e_'_'.   A  Boolean Prolog flag  is true iff  the
    Prolog  flag is present aanndd the _V_a_l_u_e  is the atom true.   Tests for
    such flags should be written as below.

            (   current_prolog_flag(windows, true)
            ->  <Do MS-Windows things>
            ;   <Do normal things>
            )

    aabboorrtt__wwiitthh__eexxcceeppttiioonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines how  abort/0 is realised.    See the description  of
         abort/0 for details.

    aaddddrreessss__bbiittss _(_i_n_t_e_g_e_r_)
         Address-size of  the  hosting machine.    Typically  32 or  64.
         Except for the maximum  stack limit, this has few  implications
         to the user.  See also the Prolog flag arch.

    aaggcc__mmaarrggiinn _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         If  this amount  of  atoms  has  been created  since  the  last
         atom-garbage collection,  perform  atom garbage  collection  at
         the  first  opportunity.    Initial  value  is  10,000.     May
         be  changed.    A  value  of 0  (zero)  disables  atom  garbage
         collection.  See also PL_register_atom().

    aallllooww__vvaarriiaabbllee__nnaammee__aass__ffuunnccttoorr _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default  is false),  Functor(arg) is  read  as if  it
         was written 'Functor'(arg).   Some applications use the  Prolog
         read/1  predicate for  reading  an application  defined  script
         language.   In these  cases, it is  often difficult to  explain
         to  non-Prolog users  of  the  application that  constants  and
         functions can only  start with a  lowercase letter.   Variables
         can be  turned into atoms  starting with  an uppercase atom  by
         calling read_term/2 using the option variable_names and binding
         the variables to their name.   Using this feature, F(x)  can be
         turned into valid syntax for such script languages.   Suggested
         by Robert van Engelen.  SWI-Prolog specific.

    aarrggvv _(_l_i_s_t_)
         List  is a  list of  atoms  representing the  command-line  ar-
         guments  used to  invoke  SWI-Prolog.    Please note  that  aallll
         arguments are included in the list returned.

    aarrcchh _(_a_t_o_m_)
         Identifier for  the  hardware and  operating system  SWI-Prolog
         is running  on.   Used to  select foreign files  for the  right
         architecture.  See also section 9.4 and file_search_path/2.

    aassssoocciiaattee _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         On Windows  systems,  this  is set  to the  filename  extension
         (pl  (default) or  pro  (can  be selected  in  the  installer))
         associated with plwin.exe.

    aauuttoollooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default) autoloading of library functions  is enabled.
         Note that  autoloading only works  if the  flag unknown is  _n_o_t
         set to fail.  See section 2.13.

    bbaacckkqquuootteedd__ssttrriinngg _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default false),  read translates  text between  back-
         quotes into a string object  (see section 4.23).  This  flag is
         mainly for compatibility to LPA Prolog.

    bboouunnddeedd _(_b_o_o_l_)
         ISO Prolog  flag.   If  true, integer  representation is  bound
         by  min_integer and max_integer.    If  false integers  can  be
         arbitrarily large and  the min_integer and max_integer are  not
         present.  See section 4.26.2.1.

    cc__cccc _(_a_t_o_m_)
         Name of the  C-compiler used to  compile SWI-Prolog.   Normally
         either gcc or cc.  See section 9.7.

    cc__llddffllaaggss _(_a_t_o_m_)
         Special linker  flags  passed to  link SWI-Prolog.    See  sec-
         tion 9.7.

    cc__lliibbss _(_a_t_o_m_)
         Libraries passed  to the C-linker  when SWI-Prolog was  linked.
         May  be  used to  determine  the  libraries  needed  to  create
         statically linked extensions for SWI-Prolog.  See section 9.7.

    cchhaarr__ccoonnvveerrssiioonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines  whether  character-conversion  takes   place  while
         reading terms.  See also char_conversion/2.

    cchhaarraacctteerr__eessccaappeess _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default),  read/1 interprets  \  escape sequences  in
         quoted atoms and strings.  May be changed.   This flag is local
         to the module in which it is changed.

    ccoommppiilleedd__aatt _(_a_t_o_m_)
         Describes when the  system has been  compiled.  Only  available
         if  the C-compiler  used  to  compile SWI-Prolog  provides  the
         __DATE__and __TIME__macros.

    ccoonnssoollee__mmeennuu _(_b_o_o_l_)
         Set  to true  in plwin.exe  to  indicate the  console  supports
         menus.  See also section 4.34.2.

    ccppuu__ccoouunntt _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         Number of  physical CPUs in  the system.   Unfortunately  there
         is  no standard  to  get  this number,  so  on  most  operating
         systems this flag  is not available.   It is marked  read-write
         both  to  allow  obtaining  this  value  later   and  to  allow
         pretending the system  has more or less  processors.  See  also
         thread_setconcurrency/2 and the library thread.  Currently this
         flag is  supported in Windows  and Linux  if /proc is  enabled.
         If  you can  provide  us with  a  C-code fragment  getting  the
         number for a specific  OS, please submit an enhancement  report
         at http://gollem.science.uva.nl/bugzilla/

    ddddee _(_b_o_o_l_)
         Set  to  true  if this  instance  of  Prolog  supports  DDE  as
         described in section 4.42.

    ddeebbuugg _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Switch debugging  mode  on/off.   If  debug  mode is  activated
         the  system  traps  encountered  spy-points  (see   spy/1)  and
         trace-points  (see   trace/1).       In   addition,   last-call
         optimisation is  disabled and the  system is more  conservative
         in destroying choice points to simplify debugging.

         Disabling these optimisations can  cause the system to run  out
         of memory on  programs that behave  correctly if debug mode  is
         off.

    ddeebbuugg__oonn__eerrrroorr _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true,  start  the  tracer  after   an  error  is  detected.
         Otherwise just continue  execution.   The goal that raised  the
         error  will normally  fail.    See  also fileerrors/2  and  the
         Prolog flag report_error.   May be changed.   Default is  true,
         except for the runtime version.

    ddeebbuuggggeerr__pprriinntt__ooppttiioonnss _(_t_e_r_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  argument is  given  as  option-list to  write_term/2  for
         printing  goals  by  the  debugger.     Modified  by  the  `w',
         `p'  and  `<_N>  d'  commands  of  the  debugger.    Default  is
         [quoted(true), portray(true), max_depth(10), attributes(portray)].

    ddeebbuuggggeerr__sshhooww__ccoonntteexxtt _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, show  the context module while printing a  stack-frame
         in the  tracer.   Normally controlled using  the `C' option  of
         the tracer.

    ddiiaalleecctt _(_a_t_o_m_)
         Fixed to swi.   The code below  is a reliable and portable  way
         to detect SWI-Prolog.

         is_dialect(swi) :-
                 catch(current_prolog_flag(dialect, swi), _, fail).

    ddoouubbllee__qquuootteess _(_c_o_d_e_s_,_c_h_a_r_s_,_a_t_o_m_,_s_t_r_i_n_g_, _c_h_a_n_g_e_a_b_l_e_)
         This flag  determines how  double  quoted strings  are read  by
         Prolog and is ---like character_escapes--- maintained  for each
         module.    If codes  (default), a  list  of character-codes  is
         returned,  if chars  a list  of  one-character atoms,  if  atom
         double  quotes  are the  same  as  single-quotes  and  finally,
         string reads the text into a Prolog string  (see section 4.23).
         See also atom_chars/2 and atom_codes/2.

    ddyynnaammiicc__ssttaacckkss _(_b_o_o_l_)
         If true,  the system uses some  form of `sparse-memory  manage-
         ment' to realise the stacks.  If  false, malloc()/realloc() are
         used for  the stacks.   In earlier  days this had  consequences
         for foreign code.   As  of version 2.5,  this is no longer  the
         case.

         Systems  using  `sparse-memory management'  are  a  bit  faster
         as  there  is  no  stack-shifter.     On   most  systems  using
         sparse-memory management  memory  is actually  returned to  the
         system  after a  garbage collection  or  call to  trim_stacks/0
         (called by prolog/0 after finishing a user-query).

    eeddiittoorr _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Determines the  editor used  by edit/1.   See  section 4.4  for
         details on selecting the editor used.

    eemmaaccss__iinnffeerriioorr__pprroocceessss _(_b_o_o_l_)
         If  true,  SWI-Prolog is  running  as an  _i_n_f_e_r_i_o_r  _p_r_o_c_e_s_s  of
         (GNU/X-)Emacs.   SWI-Prolog  assumes this  is the  case if  the
         environment variable EMACS is t and INFERIOR is yes.

    eennccooddiinngg _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Default encoding  used for  opening files in  text mode.    The
         initial  value  is   deduced  from  the   environment.      See
         section 2.17.1 for details.

    eexxeeccuuttaabbllee _(_a_t_o_m_)
         Path-name of the  running executable.  Used  by qsave_program/2
         as default emulator.

    ffiillee__nnaammee__vvaarriiaabblleess _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true  (default  false),  expand  $_v_a_r_n_a_m_e   and  ~  in  ar-
         guments  of  built-in  predicates  that  accept  a   file  name
         (open/3, exists_file/1,  access_file/2,  etc.).   The  predicate
         expand_file_name/2 can be used to expand environment  variables
         and  wildcard patterns.    This  Prolog  flag is  intended  for
         backward compatibility with older versions of SWI-Prolog.

    ffllooaatt__ffoorrmmaatt _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         C-library printf()  format  specification used  by write/1  and
         friends to  determine how floating  point numbers are  printed.
         The default is %g.   The specified value is passed  to printf()
         without  further checking.    For  example,  if you  want  more
         digits printed,  %.12g will  print all floats  using 12  digits
         instead of the default 6.

         When using  quoted-write, the output  is guaranteed to  contain
         a decimal  dot or exponent,  so read/1  reads a floating  point
         number.  See also format/[1,2], write_term/[2,3].

    ggcc _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default), the garbage collector is active.   If false,
         neither garbage-collection,  nor stack-shifts will take  place,
         even not on explicit request.  May be changed.

    ggeenneerraattee__ddeebbuugg__iinnffoo _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default) generate  code  that can  be debugged  using
         trace/0,  spy/1,  etc.      Can  be  set  to  false  using  the
         -nodebug.   The  predicate load_files/2 restores  the value  of
         this  flag  after loading  a  file,  causing  modifications  to
         be  local to  a  source  file.    Many of  the  libraries  have
         :- set_prolog_flag(generate_debug_info, false)  to  hide  their
         details from a normal trace.

    ggmmpp__vveerrssiioonn _(_i_n_t_e_g_e_r_)
         If  Prolog is  linked  with  GMP,  this flag  gives  the  major
         version of the GMP library used.  See also section 9.6.7.

    gguuii _(_b_o_o_l_)
         Set to true if XPCE is around and can be used for graphics.

    hhiissttoorryy _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         If _i_n_t_e_g_e_r >0,  support Unix csh(1)  like history as described
         in section  2.7.    Otherwise,  only support  reusing  commands
         through the command-line  editor.  The  default is to set  this
         Prolog flag  to 0  if a  command-line editor  is provided  (see
         Prolog flag readline) and 15 otherwise.

    hhoommee _(_a_t_o_m_)
         SWI-Prolog's notion  of the  home-directory.   SWI-Prolog  uses
         its   home   directory   to   find   its   startup    file   as
         <_h_o_m_e>/boot32.prc(32-bit machines) or <_h_o_m_e>/boot64.prc (64-bit
         machines) and to find its library as <_h_o_m_e>/library.

    hhwwnndd _(_i_n_t_e_g_e_r_)
         In plwin.exe,  this refers to  the MS-Windows window-handle  of
         the console window.

    iinntteeggeerr__rroouunnddiinngg__ffuunnccttiioonn _(_d_o_w_n_,_t_o_w_a_r_d___z_e_r_o_)
         ISO Prolog flag  describing rounding by  // and rem  arithmetic
         functions.  Value depends on the C-compiler used.

    iissoo _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Include some  weird ISO compatibility  that is incompatible  to
         normal SWI-Prolog behaviour.   Currently  it has the  following
         effect:

           o The  //2 (float division)  _a_l_w_a_y_s return a  float, even  if
             applied to integers that can be divided.

           o In  the standard order  of terms (see  section 4.6.1),  all
             floats are before all integers.

           o atom_length/2 yields  an instantiation  error if the  first
             argument is a number.

           o clause/[2,3]  raises  a  permission  error  when  accessing
             static predicates.

           o abolish/[1,2]  raises  a permission  error  when  accessing
             static predicates.

    llaarrggee__ffiilleess _(_b_o_o_l_)
         If present and  true, SWI-Prolog has  been compiled with  _l_a_r_g_e
         _f_i_l_e _s_u_p_p_o_r_t (LFS) and  is capable to access files  larger than
         2GB on  32-bit  hardware.   Large  file-support  is default  on
         installations built using configure that support it  and may be
         switched off using the configure option --disable-largefile.

    mmaaxx__aarriittyy _(_u_n_b_o_u_n_d_e_d_)
         ISO  Prolog  flag describing  there  is  no  maximum  arity  to
         compound terms.

    mmaaxx__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Maximum integer value  if integers are _b_o_u_n_d_e_d.   See also  the
         flag bounded and section 4.26.2.1.

    mmaaxx__ttaaggggeedd__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Maximum integer value represented as a `tagged' value.   Tagged
         integers  require  1  word  storage.      Larger  integers  are
         represented as `indirect  data' and require significantly  more
         space.

    mmaaxx__tthhrreeaaddss _(_i_n_t_e_g_e_r_)
         Provided on  multi-threaded  versions to  indicate the  maximum
         number  of  Prolog  threads  supported.     Currently  (version
         5.6.27) the limit is 100.

    mmiinn__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Minimum integer value  if integers are _b_o_u_n_d_e_d.   See also  the
         flag bounded and section 4.26.2.1.

    mmiinn__ttaaggggeedd__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Start of the tagged-integer value range.

    ooccccuurrss__cchheecckk _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  flag  controls  unification  that  creates   an  infinite
         tree  (also called  _c_y_c_l_i_c _t_e_r_m)  and  can have  three  values.
         Using  false  (default),  unification  succeeds,   creating  an
         infinite  tree.       Using   true,   unification  behaves   as
         unify_with_occurs_check/2, failing  silently.   Using error,  an
         attempt to  create  a cyclic  term results  in an  occurs_check
         exception.  The latter is intended  for debugging unintentional
         creations of  cyclic terms.   Note that this  flag is a  global
         flag modifying fundamental behaviour  of Prolog.  Changing  the
         flag from its default  may cause libraries to stop  functioning
         properly.

    ooppeenn__sshhaarreedd__oobbjjeecctt _(_b_o_o_l_)
         If  true,  open_shared_object/2 and  friends  are  implemented,
         providing access  to shared  libraries (.so  files) or  dynamic
         link libraries (.DLL files).

    ooppttiimmiissee _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, compile in optimised mode.  The initial  value is true
         if Prolog was started with the -O command-line option.

         Currently   optimise   compilation   implies   compilation   of
         arithmetic, and  deletion of redundant  true/0 that may  result
         from expand_goal/2.

         Later versions might imply various other optimisations  such as
         integrating small  predicates into  their callers,  eliminating
         constant expressions and other predictable constructs.   Source
         code  optimisation is  never  applied  to predicates  that  are
         declared dynamic (see dynamic/1).

    ppiidd _(_i_n_t_)
         Process identifier of  the running Prolog  process.   Existence
         of this flag is implementation defined.

    ppiippee _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true,  open(pipe(command), mode, Stream),   etc.  are  sup-
         ported.    Can  be  changed to  disable  the use  of  pipes  in
         applications testing this feature.  Not recommended.

    pprroommpptt__aalltteerrnnaattiivveess__oonn _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Determines prompting for  alternatives in the Prolog  toplevel.
         Default is  determinism, which implies  the system prompts  for
         alternatives if the goal succeeded while  leaving choicepoints.
         Many  classical Prolog  systems  behave  as groundness:    they
         prompt  for alternatives  if and  only  if the  query  contains
         variables.

    rreeaaddlliinnee _(_b_o_o_l_)
         If  true,  SWI-Prolog  is linked  with  the  readline  library.
         This is  done by  default if  you have  this library  installed
         on your  system.    It is  also true  for  the Win32  plwin.exe
         version of SWI-Prolog, which realises a subset  of the readline
         functionality.

    rreessoouurrccee__ddaattaabbaassee _(_a_t_o_m_)
         Set to the absolute-filename of the attached state.   Typically
         this is the file boot32.prc, the file specified with  -x or the
         running executable.  See also resource/3.

    rreeppoorrtt__eerrrroorr _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, print  error messages, otherwise  suppress them.   May
         be changed.  See also  the debug_on_errorProlog flag.   Default
         is true, except for the runtime version.

    rruunnttiimmee _(_b_o_o_l_)
         If present and  true, SWI-Prolog is  compiled with -DO_RUNTIME,
         disabling various  useful development  features (currently  the
         tracer and profiler).

    ssaavveedd__pprrooggrraamm _(_b_o_o_l_)
         If present  and  true, Prolog  has been  started  from a  state
         saved with qsave_program/[1,2].

    sshhaarreedd__oobbjjeecctt__eexxtteennssiioonn _(_a_t_o_m_)
         Extension used  by  the operating  system for  shared  objects.
         .so for  most Unix  systems and  .dll for  Windows.   Used  for
         locating  files using  the  file_type  executable.    See  also
         absolute_file_name/3.

    sshhaarreedd__oobbjjeecctt__sseeaarrcchh__ppaatthh _(_a_t_o_m_)
         Name of the environment  variable used by the system  to search
         for shared objects.

    ssiiggnnaallss _(_b_o_o_l_)
         Determine  whether Prolog  is  handling signals  (software  in-
         terrupts).   This  flag is  false if  the hosting  OS does  not
         support signal handling  or the command-line option  -nosignals
         is active.  See section 9.6.20.1 for details.

    ssyysstteemm__tthhrreeaadd__iidd _(_i_n_t_)
         Available  in  multi-threaded version  (see  section  8)  where
         the  operating  system  provides  system-wide   integer  thread
         identifiers.   The  integer  is the  thread-identifier used  by
         the  operating  system  for the  calling  thread.     See  also
         thread_self/1.

    llaasstt__ccaallll__ooppttiimmiissaattiioonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines whether  or not last-call  optimisation is  enabled.
         Normally the  value of this  flag is equal  to the debug  flag.
         As programs  may run  out  of stack  if last-call  optimisation
         is omitted,  it  is  sometimes necessary  to enable  it  during
         debugging.

    ttiimmeezzoonnee _(_i_n_t_e_g_e_r_)
         Offset in seconds  west of GMT of  the current time-zone.   Set
         at initialization  time from the  timezone variable  associated
         with the POSIX tzset() function.  See also convert_time/2.

    ttoopplleevveell__pprriinntt__aannoonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true,  top-level variables starting  with an  underscore (_)
         are printed normally.   If false they are hidden.  This  may be
         used to hide bindings in complex queries from the top-level.

    ttoopplleevveell__pprriinntt__ooppttiioonnss _(_t_e_r_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  argument   is  given   as  option-list   to  write_term/2
         for   printing    results   of   queries.         Default    is
         [quoted(true), portray(true), max_depth(10), attributes(portray)].

    ttoopplleevveell__vvaarr__ssiizzee _(_i_n_t_, _c_h_a_n_g_e_a_b_l_e_)
         Maximum  size counted  in  literals of  a  term returned  as  a
         binding for a variable  in a top-level query that is  saved for
         re-use using the $ variable reference.  See section 2.8.

    ttrraaccee__ggcc _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true  (false  is  the  default),  garbage  collections  and
         stack-shifts  will  be  reported on  the  terminal.     May  be
         changed.  Values are reported in bytes as G+T, where  G is the
         global stack  value and  T  the trail  stack value.    `Gained'
         describes the  number of bytes  reclaimed.   `used' the  number
         of bytes on the stack  after GC and `free' the number  of bytes
         allocated, but not in use.  Below is an example output.

         % GC: gained 236,416+163,424 in 0.00 sec; used 13,448+5,808; free 72,568+47,440

    ttttyy__ccoonnttrrooll _(_b_o_o_l_)
         Determines whether  the terminal  is switched to  raw mode  for
         get_single_char/1,  which also  reads the  user-actions for  the
         trace.  May be set.  See also the +/-tty command-line option.

    uunniixx _(_b_o_o_l_)
         If present and  true, the operating  system is some version  of
         Unix.  Defined  if the C-compiler used to compile  this version
         of  SWI-Prolog either  defines  __unix__ or  unix.    On  other
         systems this flag is not available.

    uunnkknnoowwnn _(_f_a_i_l_,_w_a_r_n_i_n_g_,_e_r_r_o_r_, _c_h_a_n_g_e_a_b_l_e_)
         Determines  the behaviour  if  an  undefined procedure  is  en-
         countered.    If  fail,  the predicates  fails  silently.    If
         warn,  a warning  is printed,  and  execution continues  as  if
         the  predicate was  not  defined  and if  error  (default),  an
         existence_error exception is  raised.   This flag  is local  to
         each module.  Switching this flag to  fail disables autoloading
         and thus forces complete and consistent use of use_module/[1,2]
         to load the required libraries.

    vveerrbboossee _(_A_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This flags is used by print_message/2.  If its value is silent,
         messages of type informational and banner are suppressed.   The
         -q switches the value from the initial normal to silent.

    vveerrbboossee__aauuttoollooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true the  normal  consult  message  will be  printed  if  a
         library is autoloaded.  By default this  message is suppressed.
         Intended to be used for debugging purposes.

    vveerrbboossee__llooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If false normal consult  messages will be suppressed.   Default
         is true.  The value of this flag is normally  controlled by the
         option silent(_B_o_o_l) provided by load_files/2.

    vveerrbboossee__ffiillee__sseeaarrcchh _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true  (default   false),  print  messages  indicating   the
         progress   of  absolute_file_name/[2,3]  in   locating   files.
         Intended for  debugging  complicated file-search  paths.    See
         also file_search_path/2.

    vveerrssiioonn _(_i_n_t_e_g_e_r_)
         The version identifier is an integer with value:

                          10000_*Major+ 100_*Minor+_P_a_t_c_h

         Note  that  in   releases  up  to   2.7.10  this  Prolog   flag
         yielded an atom  holding the three  numbers separated by  dots.
         The  current representation  is  much easier  for  implementing
         version-conditional statements.

    vveerrssiioonn__ddaattaa _(_s_w_i_(_M_a_j_o_r_, _M_i_n_o_r_, _P_a_t_c_h_, _E_x_t_r_a_)_)
         Part of the  dialect compatibility layer,  See also the  Prolog
         flag dialect and section 13.  _E_x_t_r_a  provides platform specific
         version information.  Currently it is simply unified to [].

    vveerrssiioonn__ggiitt _(_a_t_o_m_)
         Available if created from  a git repository.   See git-describe
         for details.

    wwiinnddoowwss _(_b_o_o_l_)
         If present and true, the operating system  is an implementation
         of Microsoft  Windows (NT/2000/XP, etc.).    This flag is  only
         available on MS-Windows based versions.

    wwrriittee__aattttrriibbuutteess _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Defines how  write/1  and friends  write attributed  variables.
         The option values are  described with the attributes option  of
         write_term/3.  Default is ignore.

    wwrriittee__hheellpp__wwiitthh__oovveerrssttrriikkee _(_b_o_o_l_)
         Internal flag used  by help/1 when writing  to a terminal.   If
         present  and true  it prints  bold  and underlined  text  using
         _o_v_e_r_s_t_r_i_k_e.

    xxppccee _(_b_o_o_l_)
         Available  and set  to  true if  the  XPCE graphics  system  is
         loaded.

    xxppccee__vveerrssiioonn _(_a_t_o_m_)
         Available and set to the version of the loaded XPCE system.


sseett__pprroolloogg__ffllaagg((_+_K_e_y_, _+_V_a_l_u_e))                                      _[_I_S_O_]
    Define  a new  Prolog flag or  change its value.    _K_e_y is an  atom.
    If  the flag is a system-defined flag that is not  marked _c_h_a_n_g_e_a_b_l_e
    above,  an  attempt to  modify the flag  yields a  permission_error.
    If  the  provided _V_a_l_u_e  does not  match  the type  of the  flag,  a
    type_error is raised.

    In  addition  to  ISO,  SWI-Prolog allows  for  user-defined  Prolog
    flags.   The type of the  flag is determined from the  initial value
    and  cannot be changed  afterwards.   Defined types are boolean  (if
    the  initial value is one  of false, true, on  or off), atom if  the
    initial value is any  other atom, integer if the value is an integer
    that  can be expressed as a 64-bit signed value.  Any  other initial
    value  results  in an  untyped  flag that  can represent  any  valid
    Prolog term.


22..1122 AAnn oovveerrvviieeww ooff hhooookk pprreeddiiccaatteess

SWI-Prolog provides a large number of hooks, mainly  to control handling
messages, debugging,  startup, shut-down, macro-expansion,  etc.   Below
is  a  summary  of  all  defined  hooks  with  an  indication  of  their
portability.

  o _p_o_r_t_r_a_y_/_1
    Hook into write_term/3 to alter the way terms are printed (ISO).

  o _m_e_s_s_a_g_e___h_o_o_k_/_3
    Hook  into  print_message/2 to  alter the  way system  messages  are
    printed (Quintus/SICStus).

  o _l_i_b_r_a_r_y___d_i_r_e_c_t_o_r_y_/_1
    Hook  into absolute_file_name/3 to define  new library  directories.
    (most Prolog system).

  o _f_i_l_e___s_e_a_r_c_h___p_a_t_h_/_2
    Hook   into   absolute_file_name/3  to   define   new   search-paths
    (Quintus/SICStus).

  o _t_e_r_m___e_x_p_a_n_s_i_o_n_/_2
    Hook  into  load_files/2  to  modify  read  terms  before  they  are
    compiled (macro-processing) (most Prolog system).

  o _g_o_a_l___e_x_p_a_n_s_i_o_n_/_2
    Same as term_expansion/2 for individual goals (SICStus).

  o _p_r_o_l_o_g___l_o_a_d___f_i_l_e_/_2
    Hook  into  load_files/2  to  load  other  data-formats  for  Prolog
    sources  from `non-file' resources.   The load_files/2 predicate  is
    the ancestor of consult/1, use_module/1, etc.

  o _p_r_o_l_o_g___e_d_i_t_:_l_o_c_a_t_e_/_3
    Hook into edit/1 to locate objects (SWI).

  o _p_r_o_l_o_g___e_d_i_t_:_e_d_i_t___s_o_u_r_c_e_/_1
    Hook into edit/1 to call some internal editor (SWI).

  o _p_r_o_l_o_g___e_d_i_t_:_e_d_i_t___c_o_m_m_a_n_d_/_2
    Hook into edit/1 to define the external editor to use (SWI).

  o _p_r_o_l_o_g___l_i_s_t___g_o_a_l_/_1
    Hook  into the tracer  to list the  code associated to a  particular
    goal (SWI).

  o _p_r_o_l_o_g___t_r_a_c_e___i_n_t_e_r_c_e_p_t_i_o_n_/_4
    Hook into the tracer to handle trace-events (SWI).

  o _p_r_o_l_o_g_:_d_e_b_u_g___c_o_n_t_r_o_l___h_o_o_k_/_1
    Hook  in spy/1, nospy/1, nospyall/0 and debugging/0 to  extend these
    control-predicates to higher-level libraries.

  o _p_r_o_l_o_g_:_h_e_l_p___h_o_o_k_/_1
    Hook in help/0, help/1 and apropos/1 to extend the help-system.

  o _r_e_s_o_u_r_c_e_/_3
    Defines a new resource (not really a hook, but similar) (SWI).

  o _e_x_c_e_p_t_i_o_n_/_3
    Old  attempt  to  a  generic  hook mechanism.     Handles  undefined
    predicates (SWI).

  o _a_t_t_r___u_n_i_f_y___h_o_o_k_/_2
    Unification  hook for attributed variables.   Can be defined in  any
    module.  See section 6.1 for details.


22..1133 AAuuttoommaattiicc llooaaddiinngg ooff lliibbrraarriieess

If ---at  runtime--- an undefined predicate  is trapped the system  will
first try  to import  the predicate  from the  module's default  module.
If this  fails the _a_u_t_o  _l_o_a_d_e_r is  activated.   On first activation  an
index  to all  library files  in all  library directories  is loaded  in
core (see library_directory/1 and file_search_path/2).   If the undefined
predicate  can be  located in  one of  the libraries  that library  file
is  automatically loaded  and  the call  to the  (previously  undefined)
predicate  is restarted.    By  default this  mechanism loads  the  file
silently.    The current_prolog_flag/2 verbose_autoload  is provided  to
get  verbose  loading.    The  Prolog  flag  autoload  can  be  used  to
enable/disable the entire auto load system.

The auto-loader only  works if the unknown  flag (see unknown/2) is  set
to  trace (default).    A more  appropriate interaction  with this  flag
should be considered.

Autoloading  only handles  (library) source  files that  use the  module
mechanism  described  in  chapter  5.     The  files   are  loaded  with
use_module/2 and only the  trapped undefined predicate will be  imported
to the module  where the undefined predicate  was called.  Each  library
directory  must hold  a file  INDEX.pl  that contains  an index  to  all
library files  in the directory.    This file consists  of lines of  the
following format:

index(Name, Arity, Module, File).

The  predicate make/0  updates the  autoload  index.   It  searches  for
all library directories (see library_directory/1 and file_search_path/2)
holding the file MKINDEX.pl or INDEX.pl.  If the  current user can write
or create  the file  INDEX.pl and  it does not  exist or  is older  than
the directory  or one  of its  files, the  index for  this directory  is
updated.  If the file MKINDEX.pl exists updating  is achieved by loading
this file, normally containing a directive calling make_library_index/2.
Otherwise make_library_index/1is  called, creating an index for all *.pl
files containing a module.

Below is an example creating a completely indexed library directory.

% mkdir ~/lib/prolog
% cd !$
% pl -g true -t 'make_library_index(.)'

If  there  are  more than  one  library  files  containing  the  desired
predicate the following search schema is followed:

 1. If  there is a  library file  that defines the  module in which  the
    undefined predicate is trapped, this file is used.

 2. Otherwise  library files  are considered  in the  order they  appear
    in  the  library_directory/1  predicate  and  within  the  directory
    alphabetically.


mmaakkee__lliibbrraarryy__iinnddeexx((_+_D_i_r_e_c_t_o_r_y))
    Create  an index for this  directory.  The  index is written to  the
    file  'INDEX.pl' in the specified directory.   Fails with a  warning
    if the directory does not exist or is write protected.


mmaakkee__lliibbrraarryy__iinnddeexx((_+_D_i_r_e_c_t_o_r_y_, _+_L_i_s_t_O_f_P_a_t_t_e_r_n_s))
    Normally  used in  MKINDEX.pl, this  predicate creates INDEX.pl  for
    _D_i_r_e_c_t_o_r_y,  indexing all files that  match one of the  file-patterns
    in _L_i_s_t_O_f_P_a_t_t_e_r_n_s.

    Sometimes  library packages consist  of one public  load file and  a
    number  of files used by  this load-file, exporting predicates  that
    should not be used  directly by the end-user.  Such a library can be
    placed  in a sub-directory of  the library and the files  containing
    public  functionality can  be  added to  the index  of the  library.
    As  an  example we  give the  XPCE library's  MKINDEX.pl,  including
    the  public  functionality of  trace/browse.pl to  the  autoloadable
    predicates for the XPCE package.

    :- make_library_index('.',
                          [ '*.pl',
                            'trace/browse.pl'
                          ]).


rreellooaadd__lliibbrraarryy__iinnddeexx
    Force  reloading  the  index  after modifying  the  set  of  library
    directories   by   changing  the   rules  for   library_directory/1,
    file_search_path/2,  adding  or  deleting  INDEX.pl  files.     This
    predicate   does   _n_o_t   update  the   INDEX.pl   files.       Check
    make_library_index/[1,2] and make/0 for updating the index files.

    Normally, the index  is reloaded automatically if a predicate cannot
    be  found  in the  index  and the  set  of library  directories  has
    changed.   Using reload_library_index/0 is necessary if  directories
    are removed or the order of the library directories is changed.


22..1144 GGaarrbbaaggee CCoolllleeccttiioonn

SWI-Prolog provides garbage-collection, last-call optimization  and atom
garbage collection.   These features  are controlled using Prolog  flags
(see current_prolog_flag/2).


22..1155 SSyynnttaaxx NNootteess

SWI-Prolog uses ISO-Prolog standard syntax, which  is closely compatible
to Edinburgh Prolog syntax.   A description of this syntax can  be found
in the  Prolog books  referenced in the  introduction.   Below are  some
non-standard or non-common constructs that are accepted by SWI-Prolog:

  o /* .../* ...*/ ...*/
    The  /* ...*/  comment statement  can be  nested.    This is  useful
    if  some  code with  /* ...*/  comment statements  in it  should  be
    commented out.


22..1155..11 IISSOO SSyynnttaaxx SSuuppppoorrtt

SWI-Prolog offers ISO compatible extensions to the Edinburgh syntax.


22..1155..11..11 PPrroocceessssoorr CChhaarraacctteerr SSeett

The processor character  set specifies the class of each  character used
for parsing Prolog  source text.   Character classification is fixed  to
use UCS/Unicode as  provided by the C-library  wchar_t based  primitives.
See also section 2.17.


22..1155..11..22 CChhaarraacctteerr EEssccaappee SSyynnttaaxx

Within quoted atoms  (using single quotes:  '<atom>' special  characters
are represented  using escape-sequences.    An escape  sequence is  lead
in  by the  backslash  (\) character.    The  list of  escape  sequences
is compatible  with the  ISO standard,  but contains  one extension  and
the interpretation of numerically specified characters  is slightly more
flexible to improve compatibility.

\a
    Alert character.  Normally the ASCII character 7 (beep).

\b
    Backspace character.

\c
    No  output.    All input  characters  up to  but not  including  the
    first  non-layout  character  are skipped.     This allows  for  the
    specification of pretty-looking  long lines.  For compatibility with
    Quintus Prolog.  Not supported by ISO. Example:

    format('This is a long line that would look better if it was \c
           split across multiple physical lines in the input')

\<RETURN>
    No  output.   Skips input till the  next non-layout character or  to
    the end of the next line.  Same intention as \c but ISO compatible.

\f
    Form-feed character.

\n
    Next-line character.

\r
    Carriage-return only (i.e. go back to the start of the line).

\t
    Horizontal tab-character.

\v
    Vertical tab-character (ASCII 11).

\xXX..\
    Hexadecimal  specification  of  a  character.    The  closing  \  is
    obligatory   according  to  the  ISO   standard,  but  optional   in
    SWI-Prolog   to  enhance  compatibility   to  the  older   Edinburgh
    standard.   The code \xa\3 emits the character 10  (hexadecimal `a')
    followed  by `3'.  Characters specified this way are  interpreted as
    Unicode characters.  See also \u.

\uXXXX
    Unicode  character specification  where the  character is  specified
    using  _e_x_a_c_t_l_y 4 hexadecimal  digits.  This  is an extension to  the
    ISO  standard fixing two problems.   First of all, where  \x defines
    a  numeric character code, it  doesn't specify the character set  in
    which  the  character should  be interpreted.    Second,  it is  not
    needed to use the idiosyncratic closing \ ISO Prolog syntax.

\UXXXXXXXX
    Same as \uXXXX, but using 8 digits to cover the whole Unicode set.

\40
    Octal   character  specification.     The  rules  and   remarks  for
    hexadecimal specifications apply to octal specifications as well.

\<_c_h_a_r_a_c_t_e_r>
    Any  character immediately preceded  by a \  and not covered by  the
    above  escape sequences is copied verbatim.   Thus, '\\' is  an atom
    consisting  of a single \ and  '\'' and '''' both describe the  atom
    with a single '.

Character      escaping      is     only      available      if      the
current_prolog_flag(character_escapes, true) is active (default).    See
current_prolog_flag/2.   Character escapes conflict with writef/2  in two
ways:   \40  is interpreted  as decimal  40 by  writef/2, but  character
escapes  handling by  read has  already interpreted  as  32 (40  octal).
Also, \l is translated to  a single `l'.  It is advised to use  the more
widely supported  format/[2,3] predicate instead.    If you insist  upon
using writef/2, either switch character_escapes to false, or  use double
\\, as in writef('\\l').


22..1155..11..33 SSyynnttaaxx ffoorr nnoonn--ddeecciimmaall nnuummbbeerrss

SWI-Prolog  implements  both  Edinburgh  and  ISO   representations  for
non-decimal numbers.   According to  Edinburgh syntax, such numbers  are
written as <_r_a_d_i_x>'<number>, where <_r_a_d_i_x> is a number between 2 and 36.
ISO defines binary,  octal and hexadecimal numbers using 0[bxo]<_n_u_m_b_e_r>.
For example:  A is 0b100 \/ 0xf00  is a valid expression.   Such numbers
are always unsigned.


22..1155..11..44 UUnniiccooddee PPrroolloogg ssoouurrccee

The ISO standard  specifies the Prolog syntax  in ASCII characters.   As
SWI-Prolog supports Unicode  in source files we must extend  the syntax.
This  section describes  the implication  for  the source  files,  while
writing international source files is described in section 3.1.3.

The  SWI-Prolog Unicode  character classification  is  based on  version
4.1.0  of the  Unicode  standard.    Please  note  that char_type/2  and
friends, intended to be used with all text except  Prolog source code is
based on the C-library locale-based classification routines.

  o _Q_u_o_t_e_d _a_t_o_m_s _a_n_d _s_t_r_i_n_g_s
    Any  character  of  any script  can  be  used in  quoted  atoms  and
    strings.      The  escape  sequences  \uXXXX  and   \UXXXXXXXX  (see
    section 2.15.1.2) were  introduced to specify Unicode code points in
    ASCII files.

  o _A_t_o_m_s _a_n_d _V_a_r_i_a_b_l_e_s
    We  handle  them in  one item  as they  are closely  related.    The
    Unicode  standard  defines  a  syntax for  identifiers  in  computer
    languages.   In this syntax identifiers start with ID_Start followed
    by  a sequence of ID_Continue codes.  Such sequences are  handled as
    a  single token  in SWI-Prolog.    The token  is a  _v_a_r_i_a_b_l_e iff  it
    starts with  an uppercase character or an underscore (_).  Otherwise
    it  is an atom.   Note  that many languages do  not have the  notion
    of  character-case.  In such languages variables _m_u_s_t be  written as
    _name.

  o _W_h_i_t_e _s_p_a_c_e
    All  characters  marked  as separators  in  the Unicode  tables  are
    handled as layout characters.

  o _O_t_h_e_r _c_h_a_r_a_c_t_e_r_s
    The first 128 characters  follow the ISO Prolog standard.  All other
    characters  not covered  by the  rules above  are considered  `solo'
    characters:   they form  single-character atoms.   We would like  to
    have a more  appropriate distinction between what is known to Prolog
    as `solo' characters and `symbol' characters.


22..1155..11..55 SSiinngglleettoonn vvaarriiaabbllee cchheecckkiinngg

A _s_i_n_g_l_e_t_o_n  _v_a_r_i_a_b_l_e is  a variable  that appears  only one  time in  a
clause.   It can always be  replaced by _, the  _a_n_o_n_y_m_o_u_s variable.   In
some  cases however  people prefer  to give  the variable  a name.    As
mistyping a variable is a common mistake, Prolog  systems generally give
a  warning (controlled  by style_check/1)  if a  variable is  used  only
once.   The system can  be informed a variable  is known to appear  once
by _s_t_a_r_t_i_n_g  it with  an underscore.    E.g. _Name.    Please note  that
any variable,  except plain _  shares with variables  of the same  name.
The term  t(_X, _X) is equivalent  to t(X, X),  which is _d_i_f_f_e_r_e_n_t  from
t(_, _).

As  Unicode requires  variables  to start  with  an underscore  in  many
languages this  schema needs to be  extended.   First we define the  two
classes of named variables.

  o _N_a_m_e_d _s_i_n_g_l_e_t_o_n _v_a_r_i_a_b_l_e_s
    Named  singletons start with  a double underscore  (__) or a  single
    underscore followed by an uppercase letter.  E.g. __var or _Var.

  o _N_o_r_m_a_l _v_a_r_i_a_b_l_e_s
    All other variables are  `normal' variables.  Note this makes _var a
    normal variable.

Any normal variable appearing  exactly ones in the clause _a_n_d  any named
singleton variables appearing  more than once are  reported.  Below  are
some examples  with warnings in  the right column.   Singleton  messages
can be suppressed using the style_check/1 directive.

___________________________________________________________________________
| test(_).      |                                                         |

| test(_a).     |Singleton variables:  [_a]                                 |
| test(A).     |Singleton variables:  [A]                                 |
| test(_A).     |                                                         |
| test(__a).    |                                                         |
| test(_, _).   |                                                         |
| test(_a, _a). |                                                         |
| test(__a, __a).S|ingleton-marked variables appearing more than once:  [__a] |

| test(_A, _A). |Singleton-marked variables appearing more than once:  [_A] |
|_test(A,_A).__|__________________________________________________________|_


22..1166 IInnffiinniittee ttrreeeess ((ccyycclliicc tteerrmmss))

SWI-Prolog  has  limited support  for  infinite  trees,  also  known  as
cyclic  terms.   Full  support  requires special  code in  all  built-in
predicates that require  recursive exploration of a  term.  The  current
version  supports cycles  terms  in  the pure  Prolog  kernel  including
the  garbage  collector  and  in  the  following   predicates:    =../2,
==/2,  =@=/2,  =/2, @</2 , @=</2,  @>=/2,  @>/2,  \==/2,  \=@=/2,  \=/2,
acyclic_term/1, bagof/3,  compare/3, copy_term/2, cyclic_term/1,  dif/2,
duplicate_term/2,  findall/3, ground/1,  term_hash/2,  numbervars/[3,4],
recorda/3,  recordz/3,   setof/3,  term_variables/2,  throw/1,   when/2,
write/1 (incomplete) .


22..1177 WWiiddee cchhaarraacctteerr ssuuppppoorrtt

SWI-Prolog  supports _w_i_d_e  _c_h_a_r_a_c_t_e_r_s, characters  with character  codes
above  255 that  cannot be  represented in  a single  _b_y_t_e.    _U_n_i_v_e_r_s_a_l
_C_h_a_r_a_c_t_e_r  _S_e_t (UCS)  is the  ISO/IEC 10646  standard  that specifies  a
unique  31-bits unsigned  integer  for any  character in  any  language.
It  is a  superset  of  16-bit Unicode,  which  in  turn is  a  superset
of ISO  8859-1 (ISO  Latin-1), a  superset of US-ASCII.  UCS can  handle
strings  holding  characters  from  multiple  languages   and  character
classification (uppercase, lowercase, digit, etc.)   and operations such
as case-conversion are unambiguously defined.

For this reason SWI-Prolog has two representations for  atoms and string
objects (see  section 4.23).   If the  text fits in  ISO Latin-1, it  is
represented as  an array  of 8-bit characters.    Otherwise the text  is
represented as an array of 32-bit numbers.   This representational issue
is completely  transparent to  the Prolog user.    Users of the  foreign
language interface as described in section 9 sometimes need  to be aware
of these issues though.

Character coding comes into  view when characters of strings need  to be
read from  or written to file  or when they  have to be communicated  to
other software  components using  the foreign  language interface.    In
this section we only deal with I/O through streams,  which includes file
I/O as well as I/O through network sockets.


22..1177..11 WWiiddee cchhaarraacctteerr eennccooddiinnggss oonn ssttrreeaammss

Although  characters   are  uniquely  coded   using  the  UCS   standard
internally, streams  and files are byte  (8-bit) oriented and there  are
a variety of  ways to represent the larger  UCS codes in an 8-bit  octet
stream.   The most popular  one, especially in  the context of the  web,
is UTF-8.   Bytes 0 ... 127 represent simply the  corresponding US-ASCII
character, while bytes 128  ... 255 are used for multi-byte  encoding of
characters placed  higher in the  UCS space.   Especially on  MS-Windows
the  16-bit Unicode  standard, represented  by pairs  of  bytes is  also
popular.

Prolog I/O streams  have a property called _e_n_c_o_d_i_n_g which  specifies the
used encoding  that influence get_code/2 and  put_code/2 as well as  all
the other text I/O predicates.

The  default  encoding  for  files  is  derived  from  the  Prolog  flag
encoding,  which   is  initialised  from  the  environment.      If  the
environment variable  LANG ends  in "UTF-8", this  encoding is  assumed.
Otherwise  the default  is  text and  the  translation  is left  to  the
wide-character  functions  of the  C-library.         The  encoding  can
be  specified  explicitly  in load_files/2  for  loading  Prolog  source
with  an  alternative encoding,   open/4 when  opening  files  or  using
set_stream/2 on  any open  stream.    For Prolog  source  files we  also
provide the  encoding/1 directive  that can  be used  to switch  between
encodings  that are  compatible to  US-ASCII  (ascii, iso_latin_1,  utf8
and  many  locales).     See  also  section  3.1.3  for  writing  Prolog
files  with non-US-ASCII  characters  and  section 2.15.1.4  for  syntax
issues.  For additional information and Unicode  resources, please visit
http://www.unicode.org/.

SWI-Prolog currently defines and supports the following encodings:

oocctteett
    Default  encoding for binary streams.  This causes the stream  to be
    read and written fully untranslated.

aasscciiii
    7-bit  encoding  in 8-bit  bytes.   Equivalent  to  iso_latin_1,  but
    generates errors and warnings on encountering values above 127.

iissoo__llaattiinn__11
    8-bit  encoding supporting many western languages.  This  causes the
    stream to be read and written fully untranslated.

tteexxtt
    C-library  default locale encoding for text  files.  Files are  read
    and  written using the C-library functions mbrtowc()  and wcrtomb().
    This may be the  same as one of the other locales, notably it may be
    the  same as iso_latin_1 for western languages  and utf8 in a  UTF-8
    context.

uuttff88
    Multi-byte encoding of full UCS, compatible to ascii.  See above.

uunniiccooddee__bbee
    Unicode  _B_i_g  _E_n_d_i_a_n.     Reads  input  in  pairs  of  bytes,   most
    significant byte first.  Can only represent 16-bit characters.

uunniiccooddee__llee
    Unicode  _L_i_t_t_l_e  _E_n_d_i_a_n.    Reads input  in  pairs of  bytes,  least
    significant byte first.  Can only represent 16-bit characters.

Note that not all encodings can represent all characters.   This implies
that  writing text  to a  stream  may cause  errors because  the  stream
cannot represent these characters.   The behaviour of a stream  on these
errors can  be controlled  using set_stream/2.   Initially the  terminal
stream write  the characters using Prolog  escape sequences while  other
streams generate an I/O exception.


22..1177..11..11 BBOOMM:: BByyttee OOrrddeerr MMaarrkk

From  section  2.17.1,  you  may  have  got  the  impression  text-files
are  complicated.   This  section  deals with  a related  topic,  making
live  often easier  for the  user, but  providing another  worry to  the
programmer.   BBOOMM or  _B_y_t_e _O_r_d_e_r _M_a_r_k_e_r is  a technique for  identifying
Unicode text-files as well  as the encoding they use.  Such  files start
with  the Unicode  character 0xFEFF,  a non-breaking,  zero-width  space
character.   This is a pretty unique  sequence that is not likely to  be
the start of  a non-Unicode file and uniquely distinguishes  the various
Unicode file  formats.   As it is  a zero-width  blank, it even  doesn't
produce any output.  This solves all problems, or ...

Some formats start of as US-ASCII and may contain  some encoding mark to
switch to UTF-8,  such as the encoding="UTF-8" in  an XML header.   Such
formats often explicitly forbid  the use of a UTF-8 BOM. In  other cases
there is additional  information telling the encoding making the  use of
a BOM redundant or even illegal.

The  BOM  is handled  by  SWI-Prolog  open/4  predicate.    By  default,
text-files are  probed for the BOM  when opened for reading.   If a  BOM
is found, the encoding is set accordingly and  the property bom(_t_r_u_e) is
available through stream_property/2.   When opening a file for  writing,
writing a BOM can be requested using the option bom(_t_r_u_e) with open/4.


22..1188 SSyysstteemm lliimmiittss


22..1188..11 LLiimmiittss oonn mmeemmoorryy aarreeaass

SWI-Prolog has  a number of  memory areas which are  only enlarged to  a
certain limit.   The  default sizes for these  areas should suffice  for
most applications, but big  applications may require larger ones.   They
are  modified by  command-line options.    The table  below shows  these
areas.   The first column  gives the option name  to modify the size  of
the area.  The option character is immediately followed  by a number and
optionally by  a k or  m.   With k or  no unit  indicator, the value  is
interpreted in Kbytes (1024 bytes), with m, the  value is interpreted in
Mbytes (10241* 024 bytes).

The local-,  global- and  trail-stack are  limited to 128  Mbytes on  32
bit processors,  or more  generally to  2 to the power bits-per-long - 5
bytes.

The  PrologScript facility  described  in  section 2.10.2.1  provides  a
mechanism for  specifying options with  the load-file.   On Windows  the
default stack-sizes  are controlled  using the Windows  registry on  the
key  HKEY_CURRENT_USER\Software\SWI\Prolog using  the  names  localSize,
globalSize and trailSize.   The value is a DWORD expressing  the default
stack size  in Kbytes.   A  GUI for modifying  these values is  provided
using the XPCE package.  To use this, start the  XPCE manual tools using
manpce/0, after which you find _P_r_e_f_e_r_e_n_c_e_s in the _F_i_l_e menu.
       ___________________________________________________________
       |_Option_|Default_|Area_name______|Description____________|_||-L||16Mlloocc||aallTssttaacckkhe|l||||ocal|stack is used

       |        |                        to  store   the  execu- |             |             ||
       |        |                        tion  environments   of |             |             ||
       |        |                        procedure  invocations. |             |             ||
       |        |                        The  space for  an  en- |             |             ||
       |        |                        vironment is  reclaimed |             |             ||
       |        |                        when  it  fails,  exits |             |             ||
       |        |                        without leaving  choice |             |             ||
       |        |                        points,   the  alterna- |             |             ||
       |        |                        tives are cut  off with |             |             ||
       |        |                                                |             |             ||

       |        |                        the  !/0  predicate  or |             |             ||
       |        |                        no  choice points  have |             |             ||
       |        |                        been created  since the |             |             ||
       |        |                        invocation and the last |             |             ||
       |        |                        subclause  is   started |             |             ||
       |        |                        (last  call   optimisa- |             |             ||
       ||       ||      |               ||tion).                  ||            |             ||

       |   -G   | 32M   |gglloobbaall ssttaacckk   ||Theusglobaled stacktois store| terms
       |        |       |               ||created during Prolog's |
       |        |       |               ||execution.    Terms  on |
       |        |       |               ||                        |
       |        |       |               ||this stack will  be re- |
       |        |       |               ||claimed by backtracking |
       |        |       |               ||to a  point before  the |
       |        |       |               ||term  was   created  or |
       |        |       |               ||by  garbage  collection |

       |        |       |               ||(provided  the term  is |
       ||       ||      ||              ||no||longer referenced).  ||
       |   -T   | 32M   |ttrraaiill ssttaacckk    ||Theusetraild stackto isstore|  as-
       |        |       |               ||signments during execu- |
       |        |       |               ||                        |
       |        |       |               ||tion.   Entries on this |
       |        |       |               ||stack remain  alive un- |

       |        |       |               ||til backtracking before |
       |        |       |               ||the  point of  creation |
       |        |       |               ||or the  garbage collec- |
       ||       ||      ||              ||tor determines||they are ||
       ||| -A   |||1M   |||aarrgguummeenntt ssttaacc||norkkneeded||any||longer.Th|e||argument stack  is

       |        |        |               used || to   store   one |
       |        |        |               of   ||the   intermediate|
       |        |        |               code ||interpreter's reg-|
       |        |        |               ister||s.     The  amount|
       |        |        |               of sp||ace needed on this|
       |        |        |               stack||is determined en- |
       |        |        |               tirel||y by the  depth in|

       |        |        |               which||terms  are nested |
       |        |        |               in  t||he   clauses  that|
       |        |        |               const||itute the program.|
       |        |        |               Overf||low is most likely|
       |        |        |               when ||using long strings|
       |        |        |               in a ||clause.           |
       |        |        |               In ad||dition, this stack|
       |        |        |               is us||ed by  some built-|
       |        |        |                    ||                  |
       |        |        |               in pr||edicates to handle|

       |        |        |               cycli||c terms.   Its de-|
       |        |        |               fault|| size   limit  is |
       |        |        |               propo||rtional   to   the|
       |        |        |               globa||l stack limit such|
       |        |        |               that || it  will   never |
       |________|________|_______________overf||low.______________|_

                        Table 2.2:  Memory areas


22..1188..11..11 TThhee hheeaapp

With  the heap,  we  refer  to the  memory  area  used by  malloc()  and
friends.  SWI-Prolog uses the area to store  atoms, functors, predicates
and their  clauses, records and  other dynamic data.   As of  SWI-Prolog
2.8.5, no limits are  imposed on the addresses returned by  malloc() and
friends.

On  some machines,  the  runtime stacks  described above  are  allocated
using `sparse  allocation'.   Virtual space up to  the limit is  claimed
at startup and committed and released while the area  grows and shrinks.
On Win32  platform this  is realised using  VirtualAlloc() and  friends.
On Unix systems this is realised using mmap().


22..1188..22 OOtthheerr LLiimmiittss

CCllaauusseess  The only  limit  on  clauses  is their  arity  (the  number  of
    arguments  to the head),  which is  limited to 1024.   Raising  this
    limit is easy and relatively cheap, removing it is harder.

AAttoommss aanndd SSttrriinnggss  SWI-Prolog  has no  limits  on  the  sizes  of  atoms
    and  strings.   read/1  and its derivatives  however normally  limit
    the  number  of newlines  in  an  atom or  string  to 5  to  improve
    error  detection  and recovery.    This  can  be switched  off  with
    style_check/1.

    The  number  of  atoms  is  limited  to  16777216  (16M)  on  32-bit
    machines.   On  64-bit machines  this is virtually  unlimited.   See
    also section 9.6.2.1.

MMeemmoorryy aarreeaass  On 32-bit hardware, SWI-Prolog data is packed in  a 32-bit
    word,  which contains  both type and  value information.   The  size
    of  the various memory areas  is limited to 128  Mb for each of  the
    areas,  except  for the  program heap,  which is  not limited.    On
    64-bit hardware there are no meaningful limits.

NNeessttiinngg ooff tteerrmmss  Many build-in  predicates process  nested terms  using
    recursive  C functions.  Too  deeply nested terms generally cause  a
    fatal crash.   All these functions avoid recursion on the right-most
    argument  and therefore terms are  not limited on the nesting  level
    of  the  last argument.    This notably  covers long  lists.    Most
    functions  use  a  stack  for correct  handling  of  rational  trees
    (cyclic  terms).  This stack is segmented, where  different segments
    are allocated using malloc().  Overflow causes a non-graceful exit.

IInntteeggeerrss  On  most systems  SWI-Prolog  is  compiled  with  support  for
    unbounded  integers by means  of the GNU GMP  library.  In  practice
    this  means that integers are bound by  the global stack size.   Too
    large  integers cause a resource_error.   On systems that lack  GMP,
    integers are 64-bit on 32 as well as 64-bit machines.

    Integers  up to the value of  the max_tagged_integerProlog  flag are
    represented more efficiently  on the stack.  For clauses and records
    the difference is much smaller.

FFllooaattiinngg ppooiinntt nnuummbbeerrss  Floating  point  numbers   are  represented   as
    C-native double precision floats, 64 bit IEEE on most machines.


22..1188..33 RReesseerrvveedd NNaammeess

The boot compiler  (see -b option) does  not support the module  system.
As large parts of  the system are written in Prolog itself we  need some
way to  avoid name clashes  with the  user's predicates, database  keys,
etc.   Like Edinburgh C-Prolog [Pereira, 1986] all predicates,  database
keys, etc. that should  be hidden from the user start with a  dollar ($)
sign (see style_check/1).


22..1199 SSWWII--PPrroolloogg aanndd 6644--bbiitt mmaacchhiinneess

SWI-Prolog support for  64-bit machines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The first consideration  is what extension to use for  the source-files.
Tradition  calls for  .pl,  but conflicts  with Perl  force the  use  of
another extension on systems where extensions have  global meaning, such
as MS-Windows.  On such systems .pro is the common alternative.

All versions of SWI-Prolog load files with the extension  .pl as well as
with the registered alternative extension without  explicitly specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your  file-manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects are achines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 64-bit platforms are capable  of running
both 32-bit and 64-bit applications.  This asks  for some clarifications
on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory-usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64 bit  addressing model.   Using  more memory  means copying more  data
between CPU and main memory, slowing down the system.

What than  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the  stacks are limited to  128MB each.   This tends to be  too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  theoretical performance loss  due to increased  memory
bandwidth implied by  exchanging wider pointers depend on the  design of
the  hardware.   We  only have  data for  the popular  IA32 vs.    AMD64
architectures.   Here is appears that the  loss is compensated for by  a
an instruction set that  has been optimized for modern programming.   In
particular, the  AMD64 has  more registers and  the relative  addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot  find a measurable  difference on AMD64.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

For those  cases where  we can choose  between 32-  and 64-bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage to use  only slightly more than  half of the memory of  64-bit
Prolog.    This argument  applies as  long as  the  application fits  in
the _v_i_r_t_u_a_l  _a_d_d_r_e_s_s _s_p_a_c_e of  the machine.   The virtual address  space
of  32-bit hardware  is 4GB,  but  in many  cases the  operating  system
provides less to user applications.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory simply  take  the model  used by  most  of
the applications  on the  OS. If  applications require  more than  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB stack  limit and  fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.  This chapter wants to explain how to run a  project.  There is
no ultimate `right'  way to do this.   Over the years we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two sections  (section 3.1 and section 3.2 only  require plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

Organisation  of  source-files  depends largely  on  the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work work with  one directory holding a couple of files  and some
files to link it  all together.  Even bigger projects will  be organised
in sub-projects each using their own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioo