Planeshift Guide To Compiling with MinGW32
==========================================

MinGW32 is an free, open source compiler with an associated toolset that
can be used for compiling Win32 executables. In conjunction with other 
free or open source software the majority of Planeshift can be compiled
under Windows without having to purchase any compiler or other licences.

This guide lists the steps necessary to download all the tools and
compile Planeshift.

1. Tools Download
=================

A) Download MinGW32 and MSYS from http://www.mingw.org
------------------------------------------------------

The MinGW package contains the compiler, header and lib files. The MSYS 
package contains the shell and make utility.

Go to the download page on the website and download the packages:
>> MinGW [bin] MinGW-3.0.0-1.exe
>> MSYS [bin] MSYS-1.0.8.exe
>> MSYS DTK [bin] msysDTK-1.0.1.exe

Run the three exe files to install the compiler and make utility. The
installation program should also add an icon for MSYS to your start menu.
Click the icon and it should open up a shell window. Type "exit" to close
the shell window again.

B) Download WinCVS from http://www.wincvs.org
---------------------------------------------

WinCVS is a free version control system that links to the source files 
for Planeshift and it's libraries at Sourceforge.com and allows you to 
easily download and update the current version of all source code files.

Go to the download page on the wincvs website and click
>> WinCvs 1.3.13.2 (Recommended release)
This will link to Sourceforge to download the file.

For now, dont bother downloading any of the optional files.

Unpack the zip file to create an install directory for WinCVS. Run the
setup program to install the file. The setup program will create a WinCVS
folder in your startup menu. Click the WinCVS to run the program.

2. Libraries Download
=====================

A) Configure WinCVS
-------------------
The first step is to create a directory structure for the library files.
Create a root directory for the project (eg. D:\Development\)

Run WinCVS. Click Admin.. Preferences from the menu if the preferences
window is not already open. Enter the following information in the dialog
box:

(On the General Tab)
[Enter the CVSROOT]
:pserver:anonymous@cvs.sourceforge.net:/cvsroot/cal3d

[Authentication]
"passwd" file on the cvs server

(On the WinCVS tab)
[HOME folder (where cvs stores your passwords)]
d:\Development

Click OK. Select View.. Browse Location.. Change from the menu and select
the d:\Development directory. Click OK, then select View.. Browse Location..
Save Settings to save this default. You should now see your empty directory
structure on the left hand window.

B) Use WinCVS to download the 3d character animation library (cal3d) source
---------------------------------------------------------------------------

Right-click on the development subdirectory and select "Checkout module" 
from the menu. Enter 'cal3d' as module name and click on 'OK', this will
start downloading the sourcecode for the cal3d library from the sourceforge
server.

C) Use WinCVS to download the Crystal Space (CS) sourcecode
-----------------------------------------------------------

Go back to Admin.. Preferences and change the [Enter the CVSROOT] to
:pserver:anonymous@cvs.sourceforge.net:/cvsroot/crystal

Right-click on the development subdirectory and select "Checkout module"
again. This time enter 'CS' as module name and click OK to start the 
download.

C) Use WinCVS to download the Crystal Entity Layer (CEL) sourcecode
-------------------------------------------------------------------

Go back to Admin.. Preferences and change the [Enter the CVSROOT] to
:pserver:anonymous@cvs.sourceforge.net:/cvsroot/cel

Right-click on the development subdirectory and select "Checkout module"
again. This time enter 'cel' as module name and click OK to start the 
download.

D) Use WinCVS to download the Planeshift sourcecode
---------------------------------------------------

Go back to Admin.. Preferences and change the [Enter the CVSROOT] to
:pserver:anonymous@cvs.sourceforge.net:/cvsroot/planeshift

Right-click on the development subdirectory and select "Checkout module"
again. This time enter 'planeshift' as module name and click OK to start 
the download.

After this process you should now have the four subdirectories full of
source code and support files. Check that appears to have been downloaded
correctly. I have occasionally had WinCVS throw a fit and refuse to update.
Normally if you close the program and open it again it will start work.

E) Download cs-win32libs-xxxx.exe
-----------------------
This library is needed for compatibility between Crystal Space and MinGW.
Go to the following FTP site and download and install the latest version 
of the cs-win32libs-xxx.exe file.  You do not need the source install
(cs-win32libs-src).  Although those files seem dependant on VC, there is
also a MINGW fork that would presumably build after building the VC 
version.

Be sure to specify a temporary directory while installing, as the install
consists of several stages.  You can download cs-win32libs-xxxx.exe from:

ftp://ftp.sunsite.dk/projects/crystal/support/win32/

F) Download MYSQL
-----------------
Download the MySQL binary (it contains the library and header files too).

http://www.mysql.com

Select the downloads tab and click on MySQL 4.0 (release) and select the 
windows build to download.
>>Windows 95/98/NT/2000/XP/2003   4.0.18   18.1M

Run the setup program and install MySQL.

G) Creating libmysql.a
----------------------
We need to create MinGW compatible libraries from the standard
Microsoft compatible libraries that ship with MySQL. Read the FAQ for 
mingw32 under the section "How can an MSVC program call a MinGW DLL, and 
vice versa?"

http://www.mingw.org/mingwfaq.shtml

Open a DOS prompt, cd to the mysql/lib/debug directory and type

reimp libmysql.lib

This will create a liblibmysql.a file. Move this file to mysql/lib and
rename it to libmysqlclient.a. You might need to specify the full path 
to reimp (c:\mingw\bin\reimp).

3. Compiling
============

A) Set the environment variables in MSYS
----------------------------------------

The makefiles will use environment variables to find the location of the
libraries. Set all these environment variables in the Windows system
environment. Also note that all slashes must be forward slashes (not the
backslashes that are more commonly used in windows directory names).

export CEL=/d/Development/cel
export CRYSTAL=/d/Development/cs
export CSCONFPATH=/d/Development/cel

B) Use MSYS to compile Cal3d
----------------------------

Run MSYS from the start menu to open the shell. And cd to the directory
in which you checked out the cal3d source code. Note: msys uses a linux
like syntax for directories. In the above example d:\development\cal3d
would be /d/development/cal3d. Now run:

..../autogen.sh
..../configure --enable-debug --prefix=/d/development/cal3d
make all
make install

This wil compile the cal3d library so that it can be used in Crystal Space.

C) Use MSYS to compile Crystal Space
------------------------------------

Run MSYS from the start menu to open the shell. And switch to the Crystal
Space source using 'cd /d/Development/cs'. Now run (note that CS uses the
JAM utility instead of make)

..../configure --enable-debug --with-libcal3d=/d/development/cal3d/ --enable-new-renderer
jam

This will build the whole of Crystal Space with the associated libraries
and demo applications. You may need to run make several times to ensure
that all the dependencies are resolved. When everything has compiled, 
try running some of the demo applications to check that everything is OK.

D) Use MSYS to compile CEL
--------------------------

CEL uses the JAMFILE utility instead of Make, so the compiling procedure
here is a little different:

cd /d/Development/cel
..../configure --enable-debug --enable-new-renderer
jam

Again, this should compile the test application celtst.exe. Run the 
application to check everything is working. I strongly suggest that you
change the follwing line in celtest.cpp from 1 to 0 before you compile.
This will enable the full testing code.

#define MINIMAL 0

E) Use MSYS to compile Planeshift
---------------------------------

Now to compile planeshift. Switch to MSYS and run:

cd /d/Development/planeshift
..../autogen.sh
..../configure --enable-debug --enable-new-renderer --with-mysqlclient-prefix=/d/mysql

Start the compilation with:

jam

This should compile planeshift.

4. Getting Help
===============

If you have trouble getting any of this to work, please feel free to 
contact me and I will do my best to help.

Email: steve.cook1@excite.com
ICQ: 39784019

Steve





