PlaneShift Compiling Guide

Select your OS and compiler:

Building PS:

Source Dates
Working Directory
Install Tools
Download Sources
Compile Sources
Get PS Art
Setup Server (optional)
Mini Scripts (optional)
Mounting External Art (optional)
Getting Help

MinGW32 is a 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 licenses.
This guide lists the steps necessary to download all the tools and compile Planeshift. This guide assumes that Visual C++.NET or Visual Studio.NET is installed. Some tools need glut, Directx 9 SDK, and python. These features are not needed so they won't be covered here. As a result there will be some compilation errors due to missing files.
This guide gives a fairly detailed description on how to get a working client up and running in Linux. It gives instructions on how to get all the required tools and how to check out the source code and configure it. At the end there you will have a PlaneShift client and a PlaneShift updater application.
There is not Mac build guide at this time. Try the Linux guide for now.

Source Dates:

Make sure you get the correct dates required for the version of PS you are building.
Note that different versions of PS require different CS/CEL dates, and PS dates
after those listed here may not be compatible with the public server.

Currently compatible with Laanx:
PS CVS date: PS_SOURCE_DATE
CS SVN revision: CS_SOURCE_REV
CEL SVN revision: CEL_SOURCE_REV

If you want to use latest PS for testing or developing purposes:
CS SVN revision for latest PS: CS_SOURCE_REV_HEAD
CEL SVN revision for latest PS: CEL_SOURCE_REV_HEAD
Note that this version of PS is NOT compatible with Laanx, yet.

Set Working Directory

First off, create your development directory. You can put it anywhere you want, however in this guide we will use the following:

/home/user/development/

c:\development\

We have no Mac guide at this time... go poke dfryer. ;)

Note that in MinGW/MSYS paths are written as follows:

/c/development/

We will place our source checkouts in sub-dirs named cs, cel, planeshift, etc.

Install Tools

Platform SDK for MSVC 8

This step is necessary if you are using VC8 Express Edition. You should download and install the Platform SDK at this location:
http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/
Remember to follow all the listed steps to get things working; include the needed dirs and edit corewin_express.vsprops as indicated.

MinGW32 and MSYS

The MinGW package contains the compiler, header and lib files.
The MSYS package contains the shell and make utility.
The MSYSDTK package contains autoconf, automake, libtool, autogen, guile, cvs, openssl, openssh, inetutils, perl and vim.
Because autoconf and automake will be outdated, we will manually update them.
Also, With MinGW version 4.1.0.0, some of the BinUtils included are broken by default so we're fixing that.

First, we'll get MinGW and a few necessary dependencies.
Note: These are the minimum required packages for the MinGW build.
Go here: http://prdownloads.sourceforge.net/mingw/ and fetch:

MinGW [bin] MinGW-4.1.0.exe
MSYS [bin] MSYS-1.0.10.exe
MSYS DTK [bin] msysDTK-1.0.1.exe
GDB [bin] gdb-5.2.1-1.exe (Optional)
MSYS Autoconf [bin] msys-autoconf-2.59.tar.bz2
MSYS Automake [bin] msys-automake-1.8.2.tar.bz2
BinUtils [bin] binutils-2.16.91-20060119-1.tar.gz

Run the exe files in the order they were downloaded to install the compiler and unzip the conf/make utilities in c:\msys\1.0\.
Then unzip the BinUtils to the c:\mingw directory.
This allows MSYS to setup the MinGW paths correctly.
The installation program should also add an icon for MSYS to your start menu.
Click the "MSYS" icon and it should open up a shell window. Type "exit" to close the shell window again.

Download the following dependencies from the same site, but do not install these yet. Their install instructions are included:
Create and place these dependencies into /usr/src. Also, create the /usr/local directory.

freetype-2.1.9-mingwPORT.tar.bz2
jpeg-6b-mingwPORT.tar.bz2
zlib-1.2.3-mingwPORT.tar.bz2
wget-1.9.1-mingwPORT.tar.bz2

The following dependencies use a scripted system to download and install them, built into their files.
For the unanswered questions below, just press enter to accept the default (in parentheses).

Installing wget

$ tar -jxvf wget-1.9.1-mingwPORT.tar.bz2
$ cd wget-1.9.1/mingwPORT
$ ./mingwPORT.sh
Download file? (Yes) No
Unarchive file? (Yes)
Archive file type? (tar.gz)
Archive file? (wget-1.9.1.tar.gz)
Archive file path? (/tmp) /c/distro
Source path? (/usr/src/wget-1.9.1)
Installation directory? (/mingw)
CFLAGS (-O3 -s -mms-bitfields -march=i686)

Installing zlib

$ tar -jxvf zlib-1.2.3-mingwPORT.tar.bz2
$ cd zlib-1.2.3/mingwPORT
$ ./mingwPORT.sh
Download file? (Yes)
Download file URI? (http://www.zlib.net)
Archive file type?
      0) unknown
      1) tar.gz
      2) tgz
      3) tar.bz2
      4) tbz2
      5) zip
Select a numeric value: (3)
Archive file? (zlib-1.2.3.tar.bz2)
Download to path? (/tmp) /usr/src
Source path? (/usr/src/zlib-1.2.3)
Installation directory? (/mingw)
CFLAGS (-O3 -s -mms-bitfields -march=i686)

Installing JPEG Support

$ tar -jxvf jpeg-6b-mingwPORT.tar.bz2
$ cd jpeg-6b/mingwPORT
$ ./mingwPORT.sh
Download file? (Yes)
Download file URI? (ftp://ftp.uu.net/graphics/jpeg)
Archive file type?
      0) unknown
      1) tar.gz
      2) tgz
      3) tar.bz2
      4) tbz2
      5) zip
Select a numeric value: (1)
Archive file? (jpegsrc.v6b.tar.gz)
Download to path? (/tmp) /usr/src
Source path? (/usr/src/jpeg-6b)
Installation directory? (/mingw)
CFLAGS (-O3 -s -mms-bitfields -march=i686)

Installing LibPNG Support
Go to LibPNG's homepage to get the latest source distribution.
We'll be using libpng-1.2.12.tar.bz2
Do not use the mingwPORT file. It is very outdated and no longer works.
Put this file in the /usr/src directory as well.

$ tar -jxvf libpng-1.2.12.tar.bz2
$ cd libpng-1.2.12
$ ./configure
$ make
$ make install

Installing FreeType2 Support

$ tar -jxvf freetype-2.1.9-mingwPORT.tar.bz2
$ cd freetype-2.1.9/mingwPORT
$ ./mingwPORT.sh
Download file? (Yes)
SF Mirror (Yes)
Which mirror from the list do you wish to use?
      0) none (Oops, I wish to cancel)
      1) jaist (JP)
      2) puzzle (CH)
      3) nchc (TW)
      4) easynews (US)
      5) ovh (FR)
      6) belnet (BE)
      7) citkit (RU)
      8) cogent (US)
      9) voxel (US)
      10) kent (UK)
      11) heanet (IE)
      12) switch (CH)
      13) mesh (DE)
      14) optusnet (AU)
Select a numeric value: (0) 4
Archive file type?
      0) unknown
      1) tar.gz
      2) tgz
      3) tar.bz2
      4) tbz2
      5) zip
Select a numeric value: (3) 3
Archive file? (freetype-2.1.9.tar.bz2)
Download to path? (/tmp) /usr/src
Source path? (/usr/src/freetype-2.1.9)
Installation directory? (/mingw)
CFLAGS (-O3 -s -mms-bitfields -march=i686)

CS Windows Libraries

Rather than having to install CS dependant components manually, Microsoft Visual C++, MinGW/MSYS, and Cygwin users can download a single package which contains all common headers, pre-built library files, and dynamic link libraries in pre-compiled form from the Crystal Space website.

The latest version is available at: http://crystalspace3d.org/support/win32/
The currently used CS revision needs version 21; newer CS is needed for version 22. Don't mix up the versions!

Run the program and install the libraries. The Default name is fine. When it asks you for the CS directory, enter C:\development\CS When you have to select the components window you can select from the menu which kind of installation you prefer. Be sure that you are installing both DirectX 9 headers and libraries files (there should be a check box that you have to check). Continue the installation. If this is your first time (and you do not yet have an SVN checkout) uncheck 'Copy DLL's to CS directory' when prompted, otherwise check the box and set the dir to c:\development\cs. To copy the files later, do so via the option in the created start menu folder.

Make sure 'Set up MSYS support' is checked when prompted.

Set Environment Variables

Right-Click My Computer on your desktop and choose Properties. Under Advanced choose Environmental Variables. Click New under either User or System variables depending on how you want it setup. If you choose System, you will have to log off to make the changes.

Variable Name: CRYSTAL (all caps)
Variable Value: C:\development\cs

Variable Name: CEL (all caps)
Variable Value: C:\development\cel

Before compiling each time in MinGW, you will also need to enter at the MSYS prompt:

export CEL=/c/development/cel
export CRYSTAL=/c/development/cs
export CSCONFPATH=/c/development/cel

Jam

You will need a tool called Jam. Jam is a replacement for make. It's a bit easier to maintain and create custom builds. If you do not already have Jam, you can find it at ftp://ftp.perforce.com/pub/jam/ - install it system wide.

cURL

To build the updater, you need the libcURL library. This is library that is used for HTTP protocol. It is what the updater application uses to update the client. It can be obtained at http://curl.haxx.se/.

CVS

You will also need a CVS client. Depending on your linux distribution, it may already be installed. If it is not, this should be obtained from your package manager or Linux distribution's website.

SVN

CS and CEL use SVN for their source repositories, so you'll need that too.
You can find the software at: http://subversion.tigris.org/
A GUI is available at: http://esvn.umputun.com/

cURL

If you want to download the updates from the server, this is required.
To build the updater, you will need to build cURL first, as MinGW does not have a compatible libcURL library available for download. This is the library that is used for the HTTP protocol. It is what the updater application uses to update the client. It can be obtained at http://curl.haxx.se/. Since you are building cURL, go ahead and get the latest version available. Do not get a binary. For this example, we will be using curl-7.15.5.tar.bz2. Place the file in /usr/src.
Make sure to read all the available support options available for cURL. The updater only uses a small subset of them, but feel free to install more if you have other uses for it.
      curl version: 7.15.5
      Host setup: i686-pc-mingw32
      Install prefix: /usr/local
      Compiler: gcc
      SSL support: no (--with-ssl / --with-gnutls)
      zlib support: enabled
      krb4 support: no (--with-krb4*)
      GSSAPI support: no (--with-gssapi)
      SPNEGO support: no (--with-spnego)
      c-ares support: no (--enable-ares)
      ipv6 support: no (--enable-ipv6)
      IDN support: no (--with-libidn)
      Build libcurl: Shared=yes, Static=yes
      Built-in manual: no (--enable-manual)
      Verbose errors: enabled (--disable-verbose)
      SSPI support: no (--enable-sspi)
      ca cert path: no

$ tar -jxvf curl-7.15.5.tar.bz2
$ cd curl-7.15.5
$ ./configure
$ make
$ make install

cURL

To build the updater, you need the libcURL library. This is the library that is used for the HTTP protocol. It is what the updater application uses to update the client. It can be obtained at http://curl.haxx.se/. The current windows package that's (easily) compatable with us is in the "Old Releases" page. Scroll down the list and download: libcurl-7.15.0-win32-msvc.zip

CVS

The 2 CVS clients recommended for Windows are WinCVS and TortoiseCVS. Both provide a GUI to access the CVS repositories.

SVN

CS and CEL use SVN for their source repositories, so you'll need that too.
The SVN client for Windows is TortoiseSVN.

cURL

To build the updater, you need the libcURL library. This is library that is used for HTTP protocol. It is what the updater application uses to update the client. It can be obtained at http://curl.haxx.se/.

Note: This section is incomplete and untested, but contains the Gentoo specific build information that was previously in the manual.

Due to the number of dependencies needed, if you wish to read the homepage listing, or dependency description please select Linux's generic dropdown selection.

via portage: #emerge curl

via portage: #emerge jam

Note: This section is incomplete and untested, but contains the Slackware specific build information that was previously in the manual.

Due to the number of dependencies needed, if you wish to read the homepage listing, or dependency description please select Linux's generic dropdown selection.

CVS

You will need also a CVS client. It should be already installed, if not you can find it in the directory slackware/d/ on your SlackWare CD or at: ftp://ftp.slackware.at/

The instructions here are tested using Ubuntu Dapper Linux.
Since Dapper is installed by default with minimal packages, many required packages for this project are not available.
To correct this, you will first need to enable the universe and multiverse repositories.
To enable these, do the following:

# sudo gedit /etc/apt/sources.list

Delete everything in the file that you have not added yourself.
Paste the following into the file and save it:

deb http://se.archive.ubuntu.com/ubuntu/ dapper main restricted
deb-src http://se.archive.ubuntu.com/ubuntu/ dapper main restricted
deb http://se.archive.ubuntu.com/ubuntu/ dapper-updates main restricted
deb-src http://se.archive.ubuntu.com/ubuntu/ dapper-updates main restricted
deb http://se.archive.ubuntu.com/ubuntu/ dapper universe
deb-src http://se.archive.ubuntu.com/ubuntu/ dapper universe
deb http://se.archive.ubuntu.com/ubuntu/ dapper-backports main restricted universe multiverse
deb-src http://se.archive.ubuntu.com/ubuntu/ dapper-backports main restricted universe multiverse
deb http://security.ubuntu.com/ubuntu dapper-security main restricted
deb-src http://security.ubuntu.com/ubuntu dapper-security main restricted
deb http://security.ubuntu.com/ubuntu dapper-security universe
deb-src http://security.ubuntu.com/ubuntu dapper-security universe
deb http://se.archive.ubuntu.com/ubuntu/ dapper multiverse
deb-src http://se.archive.ubuntu.com/ubuntu/ dapper multiverse

Now we need to refresh our sources.list file:

# sudo apt-get update

Once that is complete, we can fetch all the required packages using the following command:

# sudo apt-get --assume-yes install libjpeg62-dev x11proto-gl-dev autoconf libcurl3-dev jam bison flex-old automake1.9 libcurl3-dev libmng-dev libmikmod2-dev libogg-dev libvorbis-dev zlib1g-dev libpng3-dev build-essential cvs libtool libglu1-mesa-dev xserver-xorg-dev libxt-dev libopenal0a libopenal-dev subversion zlibc libttf2 libfreetype6-dev libfreetype6 libasound2-dev alsa-oss libxxf86vm-dev

Note: This section is incomplete and untested, but contains the Debian specific build information that was previously in the manual.

Due to the number of dependencies needed, if you wish to read the homepage listing, or dependency description please select Linux's generic dropdown selection.

via app-get: #apt-get install libcurl3-dev

via app-get: #apt-get install jam

If you are using Debian testing (which uses X.Org), then you need xlibmesa-gl-dev instead of xlibmesa-glu-dev.

Debian: #apt-get install xlibmesa-glu-dev

Testing: #apt-get install xlibmesa-gl-dev

Also, if you have flex, bison or automake other than automake1.8 installed, they should be uninstalled. They would conflict with the older versions flex-old, bison1.35 and automake1.8 needed to compile Planeshift.

#apt-get install bison-1.35 flex-old autoconf automake1.8

#apt-get install libmng-dev libmikmod2-dev libogg-dev libvorbis-dev zlib1g-dev libpng3-dev libjpeg62-dev python2.3-dev

nVidia Toolkit

Since Crystal Space needs it (independently from your graphic card, so even if you have an ATI card), you should download from www.nvidia.com the nvidia-toolkit. Use version 1.4.1. Make sure to use the appropriate file based on your chipset. To install the file, place it in the root directory and use the following command, then delete the tar.gz file.

tar -zxvf Cg-1.4.1_x86.tar.gz

tar -zxvf Cg-1.4.1_x86.tar.gz

tar -zxvf Cg-1.4.1_x86.tar.gz

# sudo tar -zxvf Cg-1.4.1_x86.tar.gz

via portage: #emerge ">=nvidia-cg-toolkit-1.4"

Server Databases

Optional section

MySQL:
If you have the intentions to run the server you have to install MySQL as well. PlaneShift uses MySQL version 5.0.

via apt-get:

# sudo apt-get --assume-yes install libdbd-mysql-perl libdbi-perl libnet-daemon-perl libplrpc-perl mysql-client-5.0 mysql-server-5.0 libmysqlclient15-dev

via portage: #emerge mysql

I recommend to select the "Without Installer version". Unzip the file in c:\ and rename the folder (which should resemble mysql-5.0.19) to simply mysql. At the end you should have: c:\mysql\

Also, 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?" You will find reimp here: http://wyw.dcweb.cn/reimp_new.zip
Copy the reimp.exe file to your /c/mingw/bin directory.
Open an msys prompt, cd to the /c/mysql/lib/debug directory and do the following:

reimp -d libmysql.lib
dlltool -k -d LIBMYSQL.def -l libmysqlclient.a
rm LIBMYSQL.def
mv libmysqlclient.a ..

WordNet:
You will also need the WordNet dictionaries. Download and install the WordNet binaries, version 2.1.

via apt-get: # sudo apt-get --assume-yes install wordnet-base wordnet

Download Sources

Cal3D

We need to build cal3d from source before we can start on Crystal Space. Cal3d is a library that is used for handling skeleton systems. This is a very nice system and can allow for fluid transformations between animations. This needs to be built/installed first because when we configure Crystal Space it has to find the cal3d libraries so it can know to build the sprcal3d plugin. Cal3D doesn't change much, so we'll just checkout latest:

/home/user/development$ cvs -d:pserver:anonymous@cal3d.cvs.sourceforge.net:/cvsroot/cal3d login (just hit enter for password)

/home/user/development$ cvs -z3 -d:pserver:anonymous@cal3d.cvs.sourceforge.net:/cvsroot/cal3d co cal3d

Crystal Space (CS)

Crystal Space 3D SDK is the engine that we use for rendering and sound.

/home/user/development$ svn co -r CS_SOURCE_REV https://svn.sourceforge.net/svnroot/crystal/CS/trunk/ cs

Crystal Entity Layer (CEL)

CEL is a layer on top of Crystal Space that is used for entity and behavior control.

/home/user/development$ svn co -r CEL_SOURCE_REV https://svn.sourceforge.net/svnroot/cel/cel/trunk/ cel

PlaneShift

Lastly, download our source:

/home/user/development$ cvs -d:pserver:anonymous@planeshift.cvs.sourceforge.net:/cvsroot/planeshift login (just hit enter for password)

/home/user/development$ cvs -z3 -d:pserver:anonymous@planeshift.cvs.sourceforge.net:/cvsroot/planeshift co -D PS_SOURCE_DATE planeshift

Updating Sources

If in the future you have the intentions to update cal3d, CS, CEL or PS because the team has decided to use another date or because you feel like you want to update it, instead of doing a checkout you have simply to update. Please, remember that cal3d, CS, and CEL must be of the same date while PS can be newer. Don't mix up versions and dates!

If you want to update to a new date:

/home/user/development$ svn update -r REVISION cs
/home/user/development$ svn update -r REVISION cel
/home/user/development$ cvs -z3 update -dPC -D "200x-xx-xx 00:00:00 UTC" planeshift

If you want to update to present time (HEAD) you have to remove the sticky date tag, like this:

/home/user/development$ svn update -r HEAD cs
/home/user/development$ svn update -r HEAD cel
/home/user/development$ cvs -z3 update -dPC -A planeshift

Obviously, after updating you have to compile again. Before doing it you should do a "jam clean" for each project you want to jam again. So, for example, if you want to rebuild PS you will do:

/home/user/development/planeshift$ jam clean
/home/user/development/planeshift$ jam -aq

Crystal Space (CS)

Crystal Space 3D SDK is the engine that we use for rendering and sound.

Right-click on the development directory and select "SVN Checkout". Specify the URL as:

https://svn.sourceforge.net/svnroot/crystal/CS/trunk/

Specify the checkout directory as "c:\development\cs", select "Revision", and paste the current CS revision number: CS_SOURCE_REV

You should now copy your CS Win Libs DLLs over to your new CS directory. Goto the start menu and do "CrystalSpace Win32 libraries"->"Copy DLLs to a CS directory". Set the directiory to c:\development\cs when prompted.

Next, copy CrystalSpaceLibs MinGW directory into a new generic directory like this:
(You may need to verify the mingw directory first.)

cp -rf /C/CrystalSpaceLibs/lib/mingw-gcc-3.4 /C/CrystalSpaceLibs/lib/mingw

Crystal Entity Layer (CEL)

CEL is a layer on top of Crystal Space that is used for entity and behaviour control.

Right-click on the development directory and select "SVN Checkout". Specify the URL as:

https://svn.sourceforge.net/svnroot/cel/cel/trunk/

Specify the checkout directory as "c:\development\cel", select "Revision", and paste the current CEL revision number: CEL_SOURCE_REV

PlaneShift

Lastly, download our source:

Right-click on the development directory and select "Checkout Module" or "CVS Checkout".
Enter "planeshift" for the module name, and set CVSROOT to:

:pserver:anonymous@planeshift.cvs.sourceforge.net:/cvsroot/planeshift

(for WinCVS, the local folder to checkout to must be C:\development\)
You need to get the specific date that's compatable with the public server, so goto the "Update Options" or "Revision" tab and select "By Date" or "Files at a certain time". Paste PS_SOURCE_DATE into the space provided.

Updating Sources

If in the future you have the intentions to update CS, CEL, or PS because the team has decided to use another date or because you feel like you want to update it, instead of doing a checkout you simply have to update. Please, remember that CS and CEL must be of the same date while PS can be newer. Don't mix up versions and dates!

CS and CEL SVNs:
Right-click on the folder of the module you want and goto TortoiseSVN->"Update to Revision". Enter a new revsion number or select HEAD to get latest. Click ok, and the files will be updated.

PS CVS:
Right-click on the folder of the module you want and goto CVS->"Update Special". (TODO: WinCVS?) To update to a new date, select "Get date/time" and enter the requested date. Make sure "create missing subfolders" is checked and "if no revision is found, use the most recent one" is NOT checked. Click ok, and the files will be updated. To update to present time (HEAD) or to a branch/tag within a module, select "Get tag/branch/revision" and type in the requested entry's name instead.

No guide yet. Try the Linux version for now.

Compile Sources

Cal3D

Since cal3d is a library in development we probably don't want to 'install' this one as root since there is a good possibility it will change in the future. Instead we will 'install' it into our working directory. This is done by using the -prefix option when we configure it.

Many people with more recent versions of automake need to open cal3d/src/cal3d/Makefile.am and either comment out or remove the line with all_libraries = @all_libraries@. Without doing that cal3d won't build.

On newer versions of Gentoo the detection of autoconf-2.60 can fail. Open cal3d's autogen.sh and search for the line listing autoconf versions. Add "autoconf-2.60" at the end of the "for" statment. Go down a few lines and change the "2.5?" to a "2.6?". Then follow the normal process below.

/home/user/development/cal3d$ ./autogen.sh
/home/user/development/cal3d$ ./configure --prefix=/home/user/development/cal3d
/home/user/development/cal3d$ make
/home/user/development/cal3d$ make install

Because we did not install cal3d we need to make sure other things can find it. This is done using the LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=/home/user/development/cal3d/src/cal3d/.libs/:$LD_LIBRARY_PATH

Crystal Space (CS)

Now we can build it (in debug mode) and use the configure line to tell it where we installed the cal3d libraries. To do this, use the prefix line that was used for Cal3d above.

/home/user/development/cs$ ./configure --enable-debug --without-java --without-python --with-libcal3d=/home/user/development/cal3d
/home/user/development/cs$ jam -aq libs plugins cs-config walktest

If you prefer to compile one step at the time do:

/home/user/development/cs$ ./configure --enable-debug --without-java --without-python --with-libcal3d=/home/user/development/cal3d
/home/user/development/cs$ jam -aq libs
/home/user/development/cs$ jam -aq plugins
/home/user/development/cs$ jam -aq cs-config
/home/user/development/cs$ jam -aq walktest

If you are using GCC 4, you will see many warnings about virtual functions during compilation. It is safe to ignore them.

We should add the CRYSTAL environment variable to the .bashrc file so applications outside the Crystal Space tree know where to find the .so's.

export CRYSTAL=/home/user/development/cs

Crystal Entity Layer (CEL)

/home/user/development/cel$ ./configure --enable-debug --without-python
/home/user/development/cel$ jam -aq libs plugins cel-config

We should add the CEL environment variable to the .bashrc file so applications outside the CEL tree know where to find the .so's.

export CEL=/home/user/development/cel

PlaneShift

/home/user/development/planeshift$ ./autogen.sh
/home/user/development/planeshift$ ./configure --enable-debug --with-libcal3d=/home/user/development/cal3d
/home/user/development/planeshift$ jam -aq client

If you also want to build the server, do this instead:

/home/user/development/planeshift$ jam -aq dbmysql client server

If you want to build the extra tools, just do "jam -a". Some tools may not build.

Run MSYS from the start menu to open the shell.

Crystal Space (CS)

Switch to the Crystal Space source dir using 'cd /c/development/cs'. Configure to debug mode and jam. (if you wish to build in optimized mode, just run configure without any arguments) If you chose to build cal3d, rather than use it from the CS win libs, you can specify it's location with: --with-cal3d=/c/development/cal3d/

./configure --enable-debug --without-java --without-python
jam -aq cs-config libs plugins walktest

This will build all the needed libraries and plugins, as well as the standard test application.
After everything compiles, try running "walktest.exe" in /c/development/cs to check that everything is ok.

Crystal Entity Layer (CEL)

Change your working directory to CEL's, and do:

./configure --enable-debug --without-python
jam -aq cel-config libs plugins celtst

You can test this build by running the demo application "celtst.exe" in /c/development/cel to check that everything is ok.

PlaneShift

Change your working directory to PS's, and do:

./autogen.sh
./configure --enable-debug
jam -aq client

If you're building the updater, you also need to add the updater to the jam command (as follows):

jam -aq client updater

If you're building the server, you also need to configure with your MySQL location:

./autogen.sh
./configure --enable-debug --with-mysqlclient=/c/mysql
jam -aq dbmysql client server

If you want to build the extra tools, just do "jam -a". Some tools may not build.

This should compile PlaneShift.

No guide yet. Try the Linux version for now.

Setup MSVC Environment

Note: MSVC 2005 (Full Edition Only): Make sure the "Show all settings" checkbox is checked in Tools->Options before continuing.
Here we will add all the directories, containing all the include and lib files that we will need to use during this compile. Under Tools->Options in you MSVC look on the left hand side for the Projects folder. Under Projects choose "VC++ Directories". In the Show Directories for: choose "Include Files". Click the new folder icon to dd the following directories:

C:\development\CS\include
C:\development\CS\include\csutil\win32
C:\development\cel\include
C:\development\curl\include
C:\mysql\include

In the Show Directories for: choose "Library Files". Click the new folder icon to add the following directories:

C:\mysql\lib\opt
C:\development\curl\

Crystal Space (CS)

Make sure that your specific 'msvc' folder has the 'read only' box unchecked before continuing.

If you have MSVC 7.0 open C:\development\CS\mk\msvc7\wkstypical.sln
If you have MSVC 7.1 open C:\development\CS\mk\msvc71\wkstypical.sln
If you have MSVC 8.0 open C:\development\CS\mk\msvc8\wkstypical.sln

Go into the 'Build' menu, and select 'configuration manager'. Change the 'Active Solution Configuration' to 'Debug'. Right click on the solution and select 'Build Solution'. To test the build of CS, run the walktest.exe in C:\development\CS. If you encounter any errors, check you have done everything correctly, and then if the problem persists, you can ask for help in the CS IRC channel: irc.freenode.net #crystalspace

Crystal Entity Layer (CEL)

Make sure that your specific 'msvc' folder has the 'read only' box unchecked before continuing.

If you have MSVC 7.0 open C:\development\cel\msvc\7\wkscel.sln
If you have MSVC 7.1 open C:\development\cel\msvc\71\wkscel.sln
If you have MSVC 8.0 open C:\development\cel\msvc\8\wkscel.sln

Build the solution. Just ignore any Python errors.

PlaneShift

Under Tools->Options in you MSVC look on the left hand side for the Projects folder. Under Projects choose "VC++ Directories". In the Show Directories for: choose "Library Files". Click the new folder icon to add the following directories:

C:\development\CS\out\debugX\libs
C:\development\cel\out\debugX\libs

You have to change X (in the path concerning CS and cel libraries) to these values, depending from the version you have of MSVC:

7 for MSVC 7
71 for Visual Studio .NET 2003/MSVC 7.1
8 for Visual Studio .NET 2005/MSVC 8

If you have MSVC.NET 7.0 open C:\development\planeshift\mk\msvc7\wkspstypical.sln
If you have MSVC.NET 2003/VC 7.1 open C:\development\planeshift\mk\msvc71\wkspstypical.sln
If you have MSVC.NET 2005/VC 8.0 open c:\development\planeshift\mk\msvc8\wkspstypical.sln

Do the following if you put mysql somewhere else than C:\mysql:
Right-click plgdbmysql, under properties->linker->general, change the "C:\mysql\lib\opt" in Additional Library Directories to whatever your location of mysql is.

Build solution.

Note: You might have to copy a few DLL files from other build directories to your PlaneShift directory if you get problems. You usually need libz-cs.dll, libcurl.dll (or similar), and libmySQL.dll.

Setting Up For Debugging

Now before you can debug the programs, you need to change some the of the project properties.
For each application:
Right-Click on the project. Under properties->debugging change:
Command to: C:\development\planeshift\(name).exe
Working directory to: C:\development\planeshift\
You should be good to go now.

Get PS Art

The artwork for PlaneShift is not included in the CVS. However this is what the updater application is for. (If you have previously downloaded a release package, you can simply copy over your art directory, everything in your data directory except for gui, and skip this step.) This connects to our update central site and downloads all the missing material. All you need is updated art and data files. This is done by editing the updaterconfig.xml file and first setting the correct mirrors to use. Our current mirror list is:

<mirrors>
    <mirror id="1" name="mir1" url="http://planeshift.mirror.thumbnail.cz/psupdater/" />
    <mirror id="2" name="mir2" url="http://www.psmirror.org/psupdater/" />
    <mirror id="3" name="backup" url="http://laanx.fragnetics.com/updater_hidden/" />
</mirrors>

Now adjust the <modules> section to only have art and data, and set the <autoinclude_os> value to 0.

Since you built the updater, do not use the --auto switch. The following should be done before every update:
1. Start the updater and click "Updater Options".
2. Select "Skip Updater Version Check".
3. Make sure "Update Programs" and "Update Root" are not selected.
4. Then save the options and click "Update".
(You can run the updater using the --auto switch to run in text-only mode). You can now start the updater.
(You can run the updater using the --auto switch to run in text-only mode). You can now start the updater.
Running it for the first time, the updater will look very bad since it does not yet have the art work. Nevertheless, let the updater run for a long time. There may be upwards of 200 MB of data to download.

Once this is complete, set a skin in psSetup and PS should be ready to run. Be sure to create your account first at our registration page if you wish to connect to the public server.

Get the Server Running

Optional section

Copy Dictionary Files

Simply copy the dictionary files from your \WordNet\2.1\dict folder to the \PlaneShift\data\dict folder.

Simply copy the dictionary files from your /usr/share/wordnet folder to the /home/user/development/planeshift/data/dict folder.

Create the Database

Make sure that MySQL is running.

Also, you should use a Command Prompt in DOS for the MySQL client commands.
You can start your MySQL server in this way:

# /etc/init.d/mysql start

Then login to the MySQL client using (default username with no password):

$ mysql -u username -ppassword

The default username is root with no password.

C:\mysql\bin\mysqld

Then login to the MySQL client using (The default username is root with no password):

C:\mysql\bin\mysql -u root

How to create a new PS DB:

mysql> create database planeshift;
mysql> GRANT ALL PRIVILEGES ON *.* TO planeshift@localhost IDENTIFIED BY 'planeshift' WITH GRANT OPTION;
mysql> quit

$ cd home/development/planeshift/src/server/database/mysql/
home/development/planeshift/src/server/database/mysql/$ mysql -u planeshift -pplaneshift

cd c:\development\planeshift\src\server\database\mysql\
mysql -u planeshift -pplaneshift

mysql> use planeshift;
mysql> source create_all.sql;
mysql> quit

The database planeshift has now been created for planeshift to use.

NOTE: If you have upgraded MySQL server to 4.1 (while the client is still 4.0) please write this in your MySQL console:

UPDATE planeshift@localhost SET Password = OLD_PASSWORD('planeshift');

Running the Server

Go to your PlaneShift directory (C:\development\planeshift) and run psserver, this will start the server.
Note: psserver requires the DOS Command Prompt to run. psclient does not.
Go to your PlaneShift directory (C:\development\planeshift) and run psserver, this will start the server.
Go to your PlaneShift directory (home/user/development/planeshift) and run psserver, this will start the server.
Go to your PlaneShift directory (home/user/development/planeshift) and run psserver, this will start the server.
Once the server has been started, you should see a "PS Server:" prompt.

Note: If you get any problems with psserver, make sure you have the latest version of MySQL 5.0 and that your libMySQL.dll file in windows\system32 is the same as the one in mysql\lib\opt.

Type the following to load the correct map and spawn all items and NPCs:

PS Server: loadmap npcroom
PS Server: spawn
PS Server: ready

Additional maps can be listed with the "maplist" command, and loaded via the "loadmap" command. To see a list of all available psserver commands, type "help". You can shut down the server with "quit".

You should now be able to start psclient and log in. (The server is localhost on port 13331). The following accounts are in the CVS DB:

Username Password Access Group
vengeance keith full GM (30)
acraig andrew normal (0)
guest guest full GM (30)

To perform server actions while logged in, as a GM character, first execute the /admin command. You will be given the list of available commands for your account's security group. When logged in with this account, you can goto the in-game help to view the full list of available commands and syntax. If you loaded any maps other than the test map "npcroom", you may teleport to them by using the command: "/teleport me map [mapname]"

Mini Scripts

Optional section

You might want to create some script so that you don't have to manually type in the environment variables every time. In this way you can also have multiple versions of CS + CEL coexisting peacefully.

$ echo \#\!/bin/sh > planeshiftserver.sh
$ echo "export CRYSTAL=$PWD/cs/" >> planeshiftserver.sh
$ echo "export CEL=$PWD/cel/" >> planeshiftserver.sh
$ echo "export CSCONFPATH=$PWD/cel/" >> planeshiftserver.sh
$ echo "cd $PWD/planeshift" >> planeshiftserver.sh
$ echo "./psserver \$@" >> planeshiftserver.sh
$ chmod +x planeshiftserver.sh

$ echo \#\!/bin/sh > planeshiftclient.sh
$ echo "export CRYSTAL=$PWD/cs/" >> planeshiftclient.sh
$ echo "export CEL=$PWD/cel/" >> planeshiftclient.sh
$ echo "export CSCONFPATH=$PWD/cel" >> planeshiftclient.sh
$ echo "cd $PWD/planeshift/" >> planeshiftclient.sh
$ echo "./psclient \$@" >> planeshiftclient.sh
$ chmod +x planeshiftclient.sh

Mounting External Art

Optional section

If you plan to do development work, or would just like to not need to copy over most of the art, you can mount the data straight from its existing location. This is highly recommended for developers using the internal art SVN.

Mount the VFS Paths

Open up the vfs.cfg file in the PlaneShift dir. Find the list of mount points (VFS.Mount.* lines) and add a mount for each custom dir you wish to use. For this example, I will mount a pre-installed package. Using the VFS syntax key at the top, add a mount as follows:

VFS.Mount.bins = $/development$/PSbins$/

I have named the mount "bins" and the dir I am using is at "/development/PSbins/".

On Windows this will be equivalent to c:\development\PSbins\

Use the Mounts

Open the cfg file of the PS application you want to use a mount. To continue the above example, I can set the CVS build client to use the installed package's maps by editing the Planeshift.Mount.zipmapdir line in psclient.cfg:

Planeshift.Mount.zipmapdir = /bins/art/world/

If you wish the server and NPC client to use these as well, modify/add that line to their cfg files too.

You can use the same mount as many times as needed, using different sub-dirs:

Planeshift.Mount.npcszip = /bins/art/npcs.zip
Planeshift.Mount.weaponzip = /bins/art/things/weapons.zip

PS mounts such as Planeshift.Mount.characterszip take a VFS path to a ZIP file, as opposed to a dir. If you wish to mount from an uncompressed dir, you need to add a slash to the end of the path:

On Windows it will be a backslash, not a forwardslash.

Planeshift.Mount.characterszip = /svn/planeshift/art/characters.zip\

On Linux it will be a forwardslash.

Planeshift.Mount.characterszip = /svn/planeshift/art/characters.zip/

On Mac it will be a forwardslash.

Planeshift.Mount.characterszip = /svn/planeshift/art/characters.zip/

Mount List

You can use the above method to easily mount most art. The full list of mounts used is as follows:

Planeshift.Mount.zipmapdir
Planeshift.Mount.characterszip
Planeshift.Mount.npcszip
Planeshift.Mount.weaponzip
Planeshift.Mount.itemzip
Planeshift.Mount.azurezip
Planeshift.Mount.bluezip
Planeshift.Mount.brownzip
Planeshift.Mount.crystalzip
Planeshift.Mount.darkzip
Planeshift.Mount.redzip
Planeshift.Mount.potionszip
Planeshift.Mount.moneyzip
Planeshift.Mount.bookszip
Planeshift.Mount.shieldszip
Planeshift.Mount.toolszip
Planeshift.Mount.naturalreszip
Planeshift.Mount.foodzip
Planeshift.GUI.Skin.Base
Planeshift.GUI.Skin.Dir

Note that the first and last mount to a directory, while the others must mount to a ZIP file unless the trailing slash is added as stated above. Also note that this isn't everything; you will still have to copy some files from the package or updater, namely your data dir and all art not mounted. This includes effects, music, sounds, apps.zip, soundlib.xml, etc. However, these things change less often than the above, and mounting the main portion of the art makes keeping things in sync much easier.

Getting Help

If you have trouble getting any of this to work, please feel free to contact us and we will do our best to help.
There is an IRC channel dedicated to providing help with building PlaneShift:

Server: irc.freenode.com
Channel: #planeshift-build