Date:	09-Jan-2003 (tested under Windows XP)
Update: 23-Feb-2003 (also tested under Windows 2000)
Author: Richard Frith-Macdonald <rfm@gnu.org>

PURPOSE
-------

This document is intended to provide a step by step instruction on how
to get the GNUstep base library into a usable state on a recent Windows
operating system (XP, 2000, and probably NT).

MinGW is a collection of header files and import libraries that allow
one to use GCC and produce native Windows32 programs that do not rely
on any 3rd-party DLLs. GNUstep has only partially been ported to MinGW
so expect some problems when trying to compile. Also, there are still
subtle problems with running GNU tools on Windows, so any problems you
may encounter may just as easly have to do with the compilation tools
you are using as with GNUstep.

MSYS is a very much cut down version of the Cygwin environment ...
providing a minimal set of tools needed to build programs using MingGW.
If you wish to build for MinGW by cross-compiling from a Cygwin
environment, please read README.cygwin instead.

The base library is only recently ported to run on MinGW.  While most
stuff works, including networking/distributed objects, there are probably
bits that have been overlooked or are untested as yet.  The only *known*
areas of code not yet ported are the zlib, SSL and XML extensions.

The gui library is only partially ported to run under MinGW ... you can
play with it, but expect to have to work on porting the library rather
than developing user applications.


PRELIMINARIES
-------------

Before we start, we need to get some preliminary Windows software -
a tool for fetching source code via CVS.

If you don't want to use Windows tools for this, you can get the
latest cygwin distribution and use the cvs client in that. The following is
for people who don't want to download all that cygwin stuff.

To get stuff from CVS you can download and install WinCVS ... which
you can find at http://sourceforge.net/projects/cvsgui You will need
to be a system administrator on your machine to install this software.
You should be able to use it without changing/setting any special
configuration options.  The one thing to remember is that the checkbox
to select whether to use UNIX line terminators instead of Windows/DOS
line terminators should be set to the unix option.


Installing and setting up MINGW and MSYS
----------------------------------------

Next, download msys-1.08 or later from
http://sourceforge.net/projects/mingw
and install it.

Next, download MinGW-2.0.0-3 or later from
http://sourceforge.net/projects/mingw
and install it inside the msys installation
(usually in c:/msys/1.0/mingw)

If you didn't install mingw in the standard location within the msys
installation, then after installing mingw, create a file called fstab in
c:/msys/<version-number>/etc, or wherever you installed msys, and make
sure it contains the line
c:/mingw /mingw
which also should be changed accordingly if you installed MinGW
somewhere else.

You may need to edit /mingw/include/winsock2.h to change the size of the
sa_data field in the sockaddr structure from 14 to 22 ... this is because
newer versions of Windows have changed the layout of this structure.
This modification is needed to be able to correctly determine the
network interface details for your machine.

It's a good idea to remove the libobjc.a and include/objc header that come
with gcc (gcc -v for location) so that they are not accidentally found
instead of the libobjc DLL that you will compile below.

Now you can open a window containg a shell by choosing MSYS from the
start menu.

At this point you may want to set the HOMEDRIVE and HOMEPATH environment
variables to point to the home directory you wish to work from (though
the defaults may be ok for you).
NB. This home directory for building software must *not* contain spaces.
(aside - MSYS uses the UNIX-style HOME environment variable, but Windows
programs, including GNUstep programs under Windows, use the HOMEDRIVE and
HOMEPATH environment variables to build a windows-style path for the home
directory.  eg. if HOMEDRIVE is C: and HOMEPATH is \MyHome then the path
to the home directory is C:\MyHome).

From this window we can now start building things.

IMPORTANT NOTE
The msys make program sometimes crashes and core-dumps (usually while
installing software).  If this happens, repeat the make command a few
times until it works ... the crash in make is not reliably repeatable
(which is probably why it has not been tracked down and fixed yet),
which means that a retry will usually work.


Obtaining GNUstep
-----------------

The main GNUstep project pages tell you how to get hold of this. You can get
the latest release of the following libraries. However, since MinGW support
is currently evolving, we recommend that you get the latest snapshot
or code from CVS.

You need things in the following order:

GNUstep-make (release, snapshot, or cvs core module)
libffcall (http://ftp.gnustep.org/pub/gnustep/lib)
GNUstep-objc (release, snapshot, or cvs dev-apps module)
GNUstep-base (snapshot, or cvs core module)

For gui ... GNUstep-back (snapshot, or cvs core module)

NB. Ensure that the GNUstep code you are attempting to use has a date
later than the date at the top of this document!  The instructions do
not apply to earlier code.


Setting up the GNUstep make environment
---------------------------------------

In the GNUstep-make (core/make) package, do './configure
--prefix=/C/GNUstep' You can of course use a different prefix to
install the GNUstep system in an alternative location.
The leading '/C' is the MSYS way of specifying that the 'C' drive is
to be used.  Older versions of the tools required a windows style
path (eg. C:/GNUstep), but using the MSYS style path is important as
it will avoid problems later!

Note: There was a comment that '--prefix=/C/GNUstep' did not work
with a bash shell as it got converted to C:\GNUstep (which is bad because 
the shell treats a \G as something entirely different. If you have this
problem, try '--prefix=C:/GNUstep' (It's probably better to use the
native Msys shell though).

Now you can type 'make install' to build and install the make package.

Once this is done, type '. GNUstep.sh' to set up your GNUstep
environment.  The environment for building software is now completely
set up, but for ease of use later, you might set up a script to be
used to set up any new shell windows you create.  Something like this
in your ~/.profile would do nicely:

export HOMEDRIVE=C:
export HOMEPATH=/home/myname
export HOME=/C/home/myname
export GNUSTEP_SYSTEM_ROOT=/C/GNUstep/System
. $GNUSTEP_SYSTEM_ROOT/Library/Makefiles/GNUstep.sh

NOTE: Sometimes the HOME variable may already be set by Windows to be
%USERPROFILE% (which is the Windows variable that contains the path of
your home folder). MSYS has problems with that as it doesn't recognise
that %USERPROFILE% is a variable name. Be sure to check that if you run
into errors.
     
     MinGW comes with a buggy 'ln -s' and Makefiles are no longer
     installed into $GNUSTEP_SYSTEM_ROOT/Makefiles so there is 
     no compatibility symlink to $GNUSTEP_SYSTEM_ROOT/Library/Makefiles



Building and installing libobjc
-------------------------------

Despite the statement in the GNUstep-HOWTO, even if you have a 3.x
compiler, you still need to install gnustep-objc as it properly
exports symbols for DLLs.

Go to gnustep-objc (or from CVS, into dev-libs/libobjc), and type

  make install

This should build and install the ObjectiveC runtime and headers for you.



Building and installing FFCALL
------------------------------

The next priority is to get the ffcall library built and installed.
You should get the latest ffcall archive from
http://ftp.gnustep.org/pub/gnustep/libs.  Currently this is
ffcall-1.8d.tar.gz

Ignore any other instructions for building this ...

First, in the shell window in which you have set up your GNUstep
environment, type

./configure --prefix=$GNUSTEP_SYSTEM_ROOT \
 --libdir=$GNUSTEP_SYSTEM_ROOT/Library/Libraries \
 --includedir=$GNUSTEP_SYSTEM_ROOT/Library/Headers

Now you can now build and install it simply by typing:

  make
  make install



Additional libraries
--------------------

There are some optional (but very strongly recommended) libraries you
can install to make GNUstep work better.  For full multilingual support
you need libiconv, and for gui applications you need libtiff, libjpeg,
and zlib.

libiconv
  Needed for multilingual character support (unicode etc)

  Get the binary package from
  http://www.zlatkovic.com/projects/libxml/index.html
  Unpack this and
    cp include/iconv.h $GNUSTEP_SYSTEM_ROOT/Library/Headers
    cp lib/iconv.lib $GNUSTEP_SYSTEM_ROOT/Library/Libraries/libiconv.a
    cp lib/iconv.dll $GNUSTEP_SYSTEM_ROOT/Tools/iconv.dll

libtiff, libjpeg, and zlib
  Needed for image handling support in the GNUstep gui libary
  (not required for GNUstep-base, though zlib can be used by the base library).

  Get the binary packages from -
  http://prdownloads.sourceforge.net/gnuwin32/tiff-3.5.7-lib.zip
  http://prdownloads.sourceforge.net/gnuwin32/tiff-3.5.7-bin.zip
  http://prdownloads.sourceforge.net/gnuwin32/libjpeg-6b-lib.zip
  http://prdownloads.sourceforge.net/gnuwin32/libjpeg-6b-bin.zip
  http://prdownloads.sourceforge.net/gnuwin32/zlib-1.1.4-lib.zip
  http://prdownloads.sourceforge.net/gnuwin32/zlib-1.1.4-bin.zip
  
  Unpack and install
  the header (.h) files in $GNUSTEP_SYSTEM_ROOT/Library/Headers
  the library (.lib) files in $GNUSTEP_SYSTEM_ROOT/Library/Libraries
  the dll files in $GNUSTEP_SYSTEM_ROOT/Tools

  Be sure to rename the .lib files to .a!

libxml2
  Needed for XML parsing support, for MacOS-X compatible
  property lists, and for documentation processing.
  NB. at the time of writing, XML support in GNUstep base has *not*
  been ported to Windows - but when it is, you will need this package.

  Get the binary package from
  http://www.zlatkovic.com/projects/libxml/binaries.html
  Unpack this and
    cd include
    tar -cf - libxml | (cd $GNUSTEP_SYSTEM_ROOT/Library/Headers; tar -xvf -)
    cd ../lib
    cp libxml2.lib $GNUSTEP_SYSTEM_ROOT/Library/Libraries/libxml2.a
    cp libxml2.dll $GNUSTEP_SYSTEM_ROOT/Tools

The following are libraries which are not currently used, but which will
be required at some point in the future -

openssl
  Needed for the SSL bundle, providing HTTPS support for NSURL.
  NB. at the time of writing, SSL support in GNUstep base has *not*
  been ported to Windows - but when it is, you will need this package.
  Get the binary package from
  http://www.kix.or.jp/~fujino/openssl
  Unpack this and
    tar -cf - openssl | (cd $GNUSTEP_SYSTEM_ROOT/Library/Headers; tar -xvf -)
    cp *.lib $GNUSTEP_SYSTEM_ROOT/Library/Libraries
    cp *.dll *.exe $GNUSTEP_SYSTEM_ROOT/Tools



Building and installing GNUstep-base
------------------------------------

Go to gnustep-base (or from CVS into the core/base directory), and type

  make install

This should automatically run the configure script for you, build the
base library and some tools, and install the whole lot (along with some
system resources).



Building and installing GNUstep-gui
-----------------------------------

To build the gui, you need to have libtiff installed ...

Go to gnustep-gui (or from CVS into the core/gui directory), and type

  make install




Building and installing GNUstep-back
------------------------------------

This software is PRE-ALPHA ... it is present in CVS for people who wish to
help porting the GNUstep backend to Windows!

In the back directory, type

  make install





Troubleshooting
---------------

Issues with updating:
Before attempting to update your GNUstep installation, be sure to stop/kill
all running GNUstep programs or services (i.e. gdomap, gdnc, gpbs) since
Windows cannot overwrite files that are currently in use.



Good Sites for Pre-Compiled Binaries
------------------------------------

Many libraries, etc from:

<http://gnuwin32.sf.net> (libtiff, libxml2)

MingW guile from

<http://www.textsure.net/~ela/devel.html>.

also need guile from

<http://sourceforge.net/project/showfiles.php?group_id=7382>

for guile-config file.
