2.4.3 Windows using MinGW

Written by Eric Sunshine, [email protected]. Originally written by Philip Wyett, [email protected]. Last updated 13 Dec 2004.

These instructions are for building Crystal Space with MinGW, the Minimalist GNU compiler for Windows.

http://www.mingw.org/

Necessary Resources

Download the following packages:

• The most recent version of the MinGW compiler and related tools. This package is typically named `MinGW-?.?.?-?.exe', where the question marks stand for the actual version number.

  http://prdownloads.sourceforge.net/mingw/

  Or:

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

• The most recent version of MSYS. This is an adjunct package for MinGW which provides additional useful utilities as well as a convenient shell environment. MSYS provides a more reliable and robust environment for the configuration and build phases of Crystal Space. It is available from the MinGW web site. This package is typically named `MSYS-?.?.?.exe', where the question marks stand for the actual version number.

  http://prdownloads.sourceforge.net/mingw/

  Or:

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

• The most recent Crystal Space Win32 Libs package. This package provides a set of additional required and optional resources used when building Crystal Space, such as zlib, libpng, libjpeg, ODE, NASM (the Netwide Assembler), etc. See cs-win32libs.

Installation

Follow these instructions to install the packages which you downloaded. Be sure to install them in the order shown.

• Install the MinGW compiler. The is a self-extracting executable. The following instructions assume you will install the MinGW package at `C:\mingw32', though you are free to install it wherever you like.
• Install MSYS. This is a self-extracting executable. During the installation, you will be asked for the location of the MinGW installation. This allows MSYS to correctly locate the MinGW tools later on when building Crystal Space. Be sure to enter the correct path (`C:/mingw32', in our example) when prompted.
• Install the `cs-win32libs' package. This is a self-extracting executable. After the installation, you should opt to also install support for the MSYS development environment. This will augment the MSYS shell startup file so a helper script named `cslibs-config' can be found when configuring Crystal Space. This script is used by the Crystal Space configure script to determine where the rest of the `cs-win32libs' resources are located.

  You may want to select "MSYS/MinGW typical" in the "Select Components" screen. You can further adjust the selection of installed components depending on your actual set up (e.g. install VisualC-related components if you plan to also use CrystalSpace with VisualC++).

Note: If you ever install a new version of MSYS, then you should also re-install the `cs-win32libs' package.

Building Crystal Space

You must configure and build Crystal Space from within the MSYS shell environment. To launch this environment, click on the MSYS icon which the installation procedure placed upon your desktop, or choose the MSYS item from the Programs menu. This will launch a Unix-like shell window into which you type commands.

Crystal Space can be built with either `make' or Jam (see GettingJam). Both tools work equally well. The `cs-win32libs' package contains a pre-built version of Jam which you can invoke simply by typing `jam' at the MSYS command prompt. In the examples below, wherever `jam' is used, you can instead substitute `make -k' if you so desire.

At the shell prompt, go to your `CS' directory with the `cd' command. For example, if Crystal Space resides at `C:\work\CS', invoke the command `cd /c/work/CS'. Next, configure and build the project with the following sequence of commands:

./configure
jam

If you prefer to build a debug version of Crystal Space, substitute the following commands for those shown above:

./configure --enable-debug
jam

If the Crystal Space source directory is read-only, if it is shared between several developers, or if you simply dislike building a project within its source tree, you can instead configure and build from a different directory. For instance:

mkdir $HOME/builddir
cd $HOME/builddir
/c/work/CS/configure --enable-debug
jam

Finally, if you want to utilize Crystal Space as a software development kit (SDK), you can install it and then clean up the detritus of the build process:

jam install
jam distclean

Additional Build Options

Sometimes it is a good idea to remove all of the built programs and executable files and start from scratch. You can do this with the following commands:

jam clean
jam

Once in a while it is even a good idea to completely clean and re-configure the project. This may be required if you are using the bleeding-edge version of Crystal Space from the SVN repository after some radical change.

jam distclean
./configure
jam

Troubleshooting

If you successfully built Crystal Space, yet find that you can not run the applications from the `CS\' root directory, a possible cause might be that the pathname leading up to the `CS\' directory might have embedded whitespace. For instance, if you installed the project in `C:\my stuff\CS', try renaming the path to `C:\my_stuff\CS' or `C:\mystuff\CS'.

Blasting the Past

If you were previously using the older, deprecated `cs_mingw_0.??.exe' package which contained the entire MinGW distribution along with other unrelated tools and resources, or the `csmingwlibs' package, it is highly recommended that you first remove the older package, as well as any residual files and resources before installing the newer MinGW, MSYS, and `cs-win32libs' packages. For best results, it would probably be wise to remove the entire old `MinGW' directory (though you may want to make a backup copy of it just in case) and clean your environment variables of any references to the old resource directories.

This document was generated using texi2html 1.76.