Porting SWI-Prolog


Below  are some  notes meant for  those who decide  to modify  or port
SWI-Prolog.  It is by no means complete.

SAVE/1 AND FRIENDS
==================

If autoconf fails to detect  a  working   save/1,  read  the comments in
pl-save.c and work on a stand-alone test version of this system using

	% gcc -DTEST pl-save.c

Two things generally need attention.  First is   to get the start of the
data segment right.  Compile and link a very small program and run 

	% nm -n a.out

on the executable.  Find the start of the data-segment and decide on the
proper definition:

	#define DATA_START
or
	#define FIRST_DATA_SYMBOL

The initialised data, uninitialised data and  malloc() heap are supposed
to be between DATA_START and sbrk(0).  If   not  (like OS2), rewrite the
code that defines the savable segments.   See   the  #ifdef  OS2's for a
start.

Second problems is the type of linking used.  See INSTALL.notes.


LOAD_FOREIGN AND FRIENDS
========================

If there is some supported version of foreign loading on your system and
it is not detected, add it.

ld -A/a.out loading may be detected, but   may  fail to compile, link or
work.  Add the proper definitions to pl-load.c.

	
VIRTUAL MEMORY BASED DYNAMIC STACKS
===================================

Based on mmap()/munmap() of /dev/zero to   allocate  memory at arbitrary
places  in  the  address   space.    This    doesn't   work   with  many
implementations of mmap() due to  various   restrictions:  cannot map at
arbitrary page boundary, can only map limited pages, cannot map private,
etc.  Work on test/mmap() if the test   fails, but you think your mmap()
is good enough.  If there are other   ways  to achieve this goal, please
let me know.  


MEMORY ERRORS (BUS ERROR; SEGMENTATION FAULT)
=============================================

It is very likely that the system crashes during  the boot compilation
called from  make (./pl   -O  -o  ...  -b ...  -c  ...).  Below  is  a
description of various such problems:


WORKING ON A SMALL PROGRAM
==========================

[skip this, it is out of date, and doesn't work anymore.  Debug using

 ./pl -d <n> -b ../boot/init.pl

 where <n> is the debugging level to be used.
]

If  you are   very lucky  the   system will  compile and perform   the
bootstrap compilation in one go.  Normally you are not.  On how to get
it through the C compiler, you  are on your  own.  If  the system does
not want to do the bootstrap compilation, write a small prolog program
that  can   be handled by the   bootstrap  compiler and work  on that.
Normally, I use

:- write('Hello World!').
:- nl.

You can  compile this using `pl -d   level -b file'.  If  this finally
writes `Hello  World' on  your terminal you  are  getting close.  Next
test program can be:

test :-
	write('Hello World'),
	nl.

$init :-
	test,
	halt.

If you can compile this and you  can run the  result by typing `a.out'
or `pl   -x  a.out -d level' you   can  try to  do   the   entire boot
compilation.  If you decide to write  more elaborate test programs you
should realise  many things are not yet   defined.  Initially  you can
only call  the foreign language   predicates, defined   in   pl-ext.c.
Constructs handles by the compiler  (,/2, !, ->/2,  ;/2, etc.)  cannot
be called   via metacall or   directives (but can be used   in program
text).


CODE USED ATOMS OR FUNCTORS
===========================

Atoms needed by the C  sources are addressed using  macros of the form
ATOM_<name>.  Functors have  the form FUNCTOR_<name><arity>.   See the
file ATOMS.  The awk script defatoms is invoked by make  to create the
necessary C source and header files.  These files are named *.i[ch].