		XPCE/SWI-Prolog runtime system
		==============================

Last Modified:	Fri Jan 29 1999


Abstract
========

This  readme  describes  how  to    make  an  XPCE-5/SWI-Prolog  runtime
executable, notably for Windows.


Requirements
============

XPCE-5/SWI-Prolog 3.2 or later release of the development system as well
as the runtime system.

Using the runtime system requires a  commercial licence to XPCE. Runtime
executables however can also be based   on  the development system. Such
runtimes may not be distributed.


Steps
=====

(1)	A fully functioning XPCE/Prolog program! The program must
	satisfy the requirements imposed by the SWI-Prolog
	qsave_program/[1,2] predicate.  See the SWI-Prolog reference
	manual for details.  The most important things are summarised
	here:

		(a) Directives that should be executed at startup-time
		of the application must be specified as

			:- initialization Goal.

		Note that loading and other compiler-directives should
		*not* be preceeded by initialization.

		(b) State, neither loading foreign extensions are
		preserved and thus need to be (re-)built at runtime.

(2)	If there are non-Prolog source files that are required by the
	application, either design a directory structure for them or
	define them as SWI-Prolog resources.  We will summarise these
	alternatives below:

		(a) Below is a typical directory structure.  `myapp'
		should be replaced by your application name.

		myapp/
		    bin/
		    swipl		% file holding a single '.'
		    xpce/
		        Defaults	% XPCE Defaults file
		    myapp/
		        <myapp's runtime files and directories>

		The directory `myapp' is known to the runtime using the
		file_search_path/2 `swi'.  So, swi(myapp) refers to the
		second `myapp' directory containing the application
		runtime files.

		All code requiring the runtime files should use
		absolute_file_name/[2,3] to exploit file-search-path.
		Many calls already do this by default.

		(b) Define each of the required runtime files using

			resource(Name, Class, PathSpec).

		where PathSpec is a path-specification (expanded using
		file-search-path) to the resource file.  Name is the
		symbolic name of the resource and Class defines it's
		type.  The type is currently not enforced.

		Class resource provides access to these objects from
		XPCE.  open_resource/3 does the same from Prolog.  For
		example:

			resource(logo,	image,	image('logo.gif')).

				...,
				send(Window, display, bitmap(resource(logo))),
				...,

(3)	Create a file typically called save.pl using the skeleton below.

		============================================================
		:- [load].

		file_search_path(myapp, swi(myapp)).	% if 2a is used

		main(Argv) :-
			<Build main Window using command-line-arguments>.

		main :-
			pce_main_loop(main).

		save(Exe) :-
			pce_autoload_all,
			qsave_program(Exe, [ emulator(swi('runtime/xpce.exe')),
					     goal(main)
					   ]).

		:- save(myapp), halt.
		===========================================================

	See the SWI-Prolog reference manual for qsave_program/2 options.
	
	Emulator defines the startup-code to use for your saved-state.
	Instead of `emulator', you can use stand_alone(true), which uses
	the currently running emulator.  This is generally the option of
	choice under Unix.  Under windows, xpce.exe provides an emulator
	that does not contain the SWI-Prolog console window. For testing
	the runtime, it is adviced to use plwin.exe (i.e. using the
	stand_alone option).

(4)	Load save.pl.  This created myapp (myapp.exe under Windows).

(5)	Create the runtime environment:

		(a) Windows
		    Under windows, this implies (in addition to 2a),
		    the runtime DLL files should be accessible.  These
		    are libpl.dll, xpce.dll, pl2xpce.dll and console.dll
		    if you are using the plwin.exe emulator.

		(b) Unix
		    Building the runtime system creates pl2xpce.so.  You
		    can also do `make pl-static' to create a fully
		    statically linked xpce executable. Using this as the
	            emulator creates a single-file executable.

(6)	Test and deliver.



		
