README.cygwin

			Using SWI-Prolog on Cygwin
			==========================

Author:   Jan Wielemaker
E-mail:   jan@swi-prolog.org
Created:  Jun 17 2001
Modified: Nov 21 2005
	  Nov 23, 2005 by Corinna Vinschen
	  Oct 14, 2014 by Corinna Vinschen

What is Cygwin?
==============

Cygwin is a POSIX emulation  environment for Windows (Windows XP SP3 and
newer).  At the time of writing  this, it supports two architectures, 32
bit i686, as well as 64 bit x86_64.  It consists of a DLL which provides
POSIX functionality on top  of Windows and lots of ported toolchains and
applications,  including  X11 server and  libs.  For further  info,  see
https://cygwin.com.


Why SWI-Prolog on Cygwin?
=========================

Cygwin provides a fairly complete emulation of the POSIX standard, while
allowing access to the native Win32 API at the same time. The SWI-Prolog
Cygwin ports use exclusively Cygwin POSIX functions.  The GUI  functions
in the pl2xpce library are using X11 functions.

Cygwin is an excellent platform for  porting native Unix applications to
Windows without much work. Though the native Win32 version of SWI-Prolog
can run under Cygwin, it is limited  in this environment. It cannot load
shared objects created in  Cygwin  and   it  doesn't  use  Cygwins POSIX
extensions to the Windows  filesystem   (mount-points,  symbolic links).
Therefore only a Cygwin version  of   SWI-Prolog  can use advanced POSIX
behaviour, which is  especially  useful   to  realise  portable advanced
process and server management.


Drawbacks?
==========

The Cygwin distro is big, even a base installation is a few 10s of Megs.
If SWI-Prolog is the only application you're interested in, it probably
isn't worth to install Cygwin.  Rather use the native Windows port.
Some POSIX functions are slow, notably fork(), due to lack of support
in the underlying OS.


Problems?
=========

Most today Unix systems are based on   the  ELF executable format, while
Windows uses  PE/COFF (Microsoft extension  of COFF).   This   has  some
consequences for making foreign libraries for SWI-Prolog. With the Cygwin
port we've started to  put all  these system  dependencies into swipl-ld,
but it is still good to know the ins and outs.

	Linking the executable, such that it exports systems and you
	can import them in your foreign libraries is now fairly easy,
	since gcc and binutils have full support to create DLLs on
	Cygwin for many years now.

	If you just make a default build, you will get just a static
	library libpl.a in $(prefix)/lib/pl-<version>/lib/${arch}-cygwin,
	and the binaries are all linked statically against this library.

	If you choose to configure with --enable-shared and after calling
	"make install", you'll get a DLL, called libswipl.dll, installed
	into

		$(prefix)/lib/pl-<version>/bin/${arch}-cygwin
		
	as well as a link library libswipl.dll.a in

		$(prefix)/lib/pl-<version>/lib/${arch}-cygwin

	"arch" is the architecture SWI-Prolog is compiled for, i686 or
	x86_64.

	This file is used for linking stand-alone embedded executables
	and foreign libraries against the libswipl DLL.

	* Creating a foreign library
	This is a bit complicated, but luckily hidden from you.  The
	basic sequence is

		gcc -shared -o mylib.dll <input files> \
		-L$(prefix)/lib/pl-<version>/lib/${arch}-cygwin -lswipl ...

	plus the required system libraries.

	To make life a bit easier in your Makefiles, we've put this
	in swipl-ld, so you can do on any platform for which swipl-ld is
	aware of the proper sequence:

		swipl-ld -shared -o mylib <input files>

	If you use the -v option as in
	
		swipl-ld -v -shared ...

	you can see what system libraries are necessary when linking.
	Or simply ask pl:

		pl -dump-runtime-variables | grep PLLIBS


Mixing Cygwin and native SWI-Prolog?
====================================

It's not possible to use  foreign libraries built using the above Cygwin
sequence on the  native  SWI-Prolog  and  visa versa.  This is caused by
native   SWI-Prolog using MSVCRT*.lib,  which is mutually exclusive with
the Cygwin POSIX library.