		Installing XPCE/Prolog from the SOURCES
		=======================================

			   Jan Wielemaker
			(jan@swi.psy.uva.nl)

History:	Fri Apr 26, 1996 for version 4.8.17 (complete rewrite)
		Tue Jan 21, 1997 updated for 4.9.1  (minor changes)
		Fri Aug 29, 1997 updated for 4.9.3  (minor changes)
		Mon Dec  8, 1997 updated for 4.9.7  (minor changes)
		Fri Feb  5, 1999 updated for 5.0.0  (deleted old stuff)

Configuration, compilation and installation is based on the GNU autoconf
package. General comments on installing packages   based on autoconf are
in the file INSTALL.

Required tools
==============

	# GNU-Make
	We're using version 3.76.  Many other versions will do as well,
	but non-gnu versions of make will fail.

	# GCC
	Necessary on most machines, though you might get away with
	another ANSI C compiler.  Check the Makefile carefully for
	the various flags passed to compiler in that case.  The only
	non-gcc compiler used by us is MSVC++ 5.0 for the Win32 version.

	Most GCC versions these days are fine.  We use egcs-1.0.3 and
	gcc-2.7.2.

	You need g++ to compile the C++ interface, but if you don't
	have it, configure will automatically exclude the C++ interface.
	libg++ is not required *NOTE: C++ is currently not supported*

	# libXpm
	The X11 XPM (XPixMap) format libary for handling coloured and
	masked images.  Not strickly necessary, but without it .xpm
	files cannot be handled and various of the library components
	and demo programs use XPM files.  XPM is an X11 contrib package.
	You can fetch the sources from many places on the net, or from
	
	    ftp://swi.psy.uva.nl/pub/xpce/util/images/xpm-3.4i.tar.gz

	# libjpeg
	The JPEG group library for handling JPEG images.  When not
	available, jpeg images cannot be handled. The sources for this
	library are in:

	    ftp://swi.psy.uva.nl/pub/xpce/util/images/jpegsrc.v6a.tar.gz

	which, again, can be found at many other places on the net.


For all other required tools, both the   GNU,  BSD and System-V versions
are supposed to work properly. Our path   prefers the tools in the order
GNU, BSD (UCB), System-V. If you have trouble,  you may want to try this
order and inform us about your experiences.


Bluffers Installation Guide
===========================

To install XPCE/SWI-Prolog from the sources:

	1) Build SWI-Prolog according to the instructions and install it.
	2) Determine an installation prefix (normally use the same as for
	   SWI-Prolog, we use `solaris' in this example).
	3) Run the following commands

		% mkdir solaris
		% cd solaris
		% ../src/configure
		% make
		% make install

XPM colour image files
======================

When available, XPCE will use  libXpm  to   deal  with  XPM image files,
providing portable full-colour images with mask   and hot-spot, ready to
use  as  icons  or  cursors   on    both   X11  and  Windows  platforms.
Unfortunately, libXpm is not part of   many  standard X11 distributions,
and should thus be installed prior to   running  configure for XPCE. You
can find a version of the xpm sources in

	ftp://swi.psy.uva.nl/pub/xpce/util/images/xpm-3.4i.tar.gz.

If you make a version for  distribution,   it  is  good practice to link
using the static version of libXpm.

JPEG colour image files
=======================

When available, XPCE will use libjpeg to deal with JPEG image files.
The jpeg format is especially useful for handling large full-colour
images of real-world scenes.  JPEG reading is based on the jpeg library
as provided by the independent JPEG group.  The source for this library
is free, and available from

	ftp://swi.psy.uva.nl/pub/xpce/util/images/jpegsrc.v6a.tar.gz


===========================
Detailed Installation Guide
===========================

We start at the SWI-Prolog  installation,   as  this  needs some special
considerations on some platforms.


Choosing the build-directory
============================

You can place the directory for   building  XPCE/Prolog anywhere. A good
choice is /usr/local/src or, if you are   installing  as a private user,
$HOME/src. Unpack the Prolog and XPCE archives from the same directory:

	% gunzip < pl-<version>.tar.gz | tar xvfB -
	% gunzip < xpce-<version>.tar.gz | tar xvfB -

NOTES:
	* Some versions of tar hate reading from a pipe.  In that case
	use `gunzip file.tar.gz' followed by `tar xvf file.tar' to extract
	the archives

	* If you are using GNU-tar, `tar zxvf file.tar.gz' is easier.


Choosing a build sub-directory
==============================

For easy cleanup or building for   multiple directories, both SWI-Prolog
and XPCE are normally built in a   directory  next to the src directory.
The name is not important. Good examples  are `sunos' `solaris', etc. In
the examples below, we use `solaris'.


The Destination Prefix (configure --prefix=dir)
===============================================

GNU autoconf-based packages accept the   flag  --prefix=<dir> to specify
the destination. The installation will use the following subdirectories:

	bin			For making *links* to the executables
	man/man1		For installing the manual pages
	include			For installing the SWI-Prolog.h header file
	lib/pl-<version>	For installing libs, executables, etc.
	lib			For installing public shared objects (if any)

The default prefix is /usr/local.  If   you  choose  another one (assume
/home/projects/bigmoney), do (if the  directory   structure  is  not yet
available):

	% cd /home/projects/bigmoney
	% mkdir bin man man/man1 include lib

Make sure the binary directory is in your PATH!

Preparing SWI-Prolog
====================

	% cd pl-<version>
	% mkdir solaris
	% cd solaris
	% ../src/configure

Shared libraries or not?
------------------------

By default, the installation atempts to   build SWI-Prolog and load xpce
as a shared object (.so file on   most  Unix machines) into Prolog. This
installation is better to maintain and   prepares SWI-Prolog for loading
custom extensions written in C in a well supported manner.

At the moment, shared libraries are *known* to work on:

	* SunOs 4.1.x
	* Solaris 2.x
	* SGI/Irix 5.x
	* Linux when using ELF binary format
	* Win32 (DLL interface)

It is likely to work  on  any   system  using  ELF binaries or something
compatible (many SVR4 systems).

By  default,  SWI-Prolog  will  try  to  configure  the  shared  library
interface and the XPCE configure run will   notify  this and prepare for
building a shared object.

Older versions of gcc (prior 2.7?) on Sun  require the Sun version of LD
rather than the GNU version to create  shared objects. In that case, add
-B<dir-holding-system-version-of-ld> to the CFLAGS.

****************************************************************

Preparing XPCE
==============

XPCE extracts most information about  the configuration from SWI-Prolog,
so it is generally much easier. Most of the configure run is simple, but
configure needs to find out where the   X11  libraries and include files
are  and  you  may  have   multiple.    Normally,   it  will  first  try
/usr/include/X11 and /usr/lib. If  you  have   only  one  version of X11
around, generally configure will be able to find it.

If you have multiple copies of X11 around,   you have to decide which to
use. If you are compiling for local  usage,   use  the  one most of your
local packages use to improve resource   sharing. Otherwise, use the one
distributed with the OS or known to be most commonly in use by your user
community. For example, our system has the   MIT X11R6 libs and includes
in  /usr/lib  and  /usr/include/X11  and  the  OpenWindows  versions  in
/usr/openwin/lib  and  /usr/openwin/include/X11.  For  local  usage,  we
configure without options to use the X11R6  version, used by most of the
other X11 software we run locally. For distribution, we configure using:

	--x-includes=/usr/openwin/include --x-libraries=/usr/openwin/lib

Checking Program versions
-------------------------

Just to make sure your programs are accessible and of the right version,
try:

	% pl -v
	SWI-Prolog version 3.2.2 for sparc-solaris2.5
	% make -v
	GNU Make version 3.76, by Richard Stallman and Roland McGrath.
	...
	% gcc -v
	Reading specs from /usr/local/lib/gcc-lib/sparc-sun-solaris2.5/2.7.2/specs
	gcc version 2.7.2

Now, run configure:

	% cd xpce-<version>
	% mkdir solaris
	% ../src/configure <options>
					     
Building the library
====================

Now, make the XPCE library:

	% make xpce

If you have configured for using shared libraries, the -fPIC flag should
be passed to the compiler. If this is  not the case, please look closely
at the steps above. If all goes well, the compilation should finish with
few warnings, resulting in the library libXPCE.a


Building the interface:
=======================

With write premission to the Prolog home directory, now do the following
to make the interface.
					     
	% make pl-itf

This command will run  either  `make   pl-shared'  or  `make pl-static',
depending on whether SWI-Prolog handles shared objects. The first builds
the pl2xpce.so shared object, and the   second builds an XPCE executable
holding both the Prolog kernel and the XPCE library called `xpce'.

Both versions will put various things   in the SWI-Prolog home directory
to make XPCE known to Prolog:

	* A link to the xpce build-directory
	* A plrc script to register the xpce library
	* A Makefile to recompile the XPCE/Prolog quick-load-files

Testing XPCE
============

Now, if you have build  for  a   shared  object,  xpce  is a dynamically
loadable Prolog library, so to test it simply do:

	% pl
	?- manpce.

which should start the manual tools.

If you built the xpce executable using `make pl-static', do:

	% ./xpce
	?- manpce.

****************************************************************

Installing the XPCE library
===========================

Finally, to install the XPCE libraries, do:

	% make install

Which will:

	# Create a directory xpce-<version> in the Prolog home and
	copy the Prolog libraries, manual data and other resources
	into this directory.

	# In the Prolog home, make a link from xpce to xpce-<version>

	# run `make' in the Prolog home directory to make quick-load
	versions of some large and frequently used library packages.

	# in $exec_prefix/bin, make links to the xpce and xpce-client
	executables
