@c -*-texinfo-*-
@node HOWTO CS Project DevCPP, HOWTO Create RPM, HOWTO Creating External Application Using KDevelop, Making Own Projects
@subsection Creating an External Crystal Space Application Using Dev-CPP
@cindex External Crystal Space Application
@cindex Dev-CPP

This section describes how you can use Dev-@sc{cpp} to compile external
applications using Crystal Space and @sc{cel}. Crystal Space does not presently
have project files for Dev-@sc{cpp} so, at this time, you will need to use
MinGW and @sc{msys} to build Crystal Space itself, however, for your own
external applications, you can use Dev-@sc{cpp}.

@subsubheading External Application Requirements

First, configure, build, and install Crystal Space (and optionally @sc{cel})
using MinGW and @sc{msys}.

If you installed Crystal Space in a non-standard location you probably
will need to set the @samp{CRYSTAL} environment variable to point at the
the location where the @sc{sdk} was installed.  For instance, if you specified
@samp{--prefix=/site/sdk} when configuring Crystal Space, then you will need to
set @samp{CRYSTAL} to @file{/site/sdk}.

If you plan to use @sc{cel} then you also must set the @samp{CEL} environment
variable.

@subsubheading Specifying the Compiler

Chances are, the compiler which is provided by Dev-@sc{cpp} is not compatible
with the built Crystal Space since Crystal Space is compiled using the version
of MingW which you have installed.  The easiest way to avoid problems with
compiler versions here is to define a new compiler in Dev-@sc{cpp}. To do so,
invoke the @emph{Tools/Compiler Options} menu item and click on the green
@samp{+} icon to add a compiler called MinGW. Make sure that that compiler is
active in the popup and then switch to the @emph{Directories} tab.  On that tab
change the path of everything to point to your MinGW installation rather than
the Dev-@sc{cpp} versions. In the @emph{Binaries} sub-tab you have to add both
the @file{bin} directory of MinGW, as well as the @file{bin} directory of
@sc{msys}, and remove the path to Dev-@sc{cpp}. In the @emph{Libraries}
sub-tab add the path to the MinGW @file{lib} directory, and remove the path
to Dev-@sc{cpp}. Do the same for on @emph{C Includes} sub-tab, add MinGW and
remove Dev-@sc{cpp}. In the @emph{C++ Includes} tab you have to add the
correct @samp{C++} MinGW @file{include} directory, and remove the Dev-@sc{cpp}
directory.  If this is all done correctly you should now be able to use the
compiler from MinGW.

@subsubheading Creating a New Project

Select the @samp{File/New/Project} menu and choose @samp{Console Application}
as the project type. Select an appropriate name and make sure @samp{C++} is
selected as the language. Save the project file in an appropriate directory.
It is best to make a new directory for the project file and all other files
related to the project.

If this is done succesfully Dev-@sc{cpp} will open with an unsaved
@file{main.cpp}. Don't save it yet.

@subsubheading Project Settings

First, you need to prepare various settings in the project. Select the
@emph{Project/Project Options} menu.  Navigate to the @emph{Compiler} tab and
switch to the new MinGW compiler which you defined earlier.  Next, go to the
@emph{Parameters} tab where you need to add the Crystal Space (and optionally
@sc{cel}) libraries with which you want to link. For Crystal Space, assuming 
that no special @samp{--prefix} was used, the libraries will usually be in 
@file{c:\msys\1.0\local\lib} if @sc{msys} was installed in @file{c:\msys}, 
adjust the path(s) as necessary. If not, then you can access the directories 
from the build location with a path that looks somewhat like this: 
@file{..\CS\out\msysx86\optimize\libs}. Substitute @file{debug} for 
@file{optimize} if you build the project in debug mode.

If you installed the Crystal Space @sc{sdk}, add the following libraries:

@example
..\CS\lib\libcrystalspace.a
@end example

@noindent
If you did not install the @sc{sdk}, then add the directories from the build
directory (subtituting @samp{debug} for @samp{optimize} if you build in debug
mode):

@example
..\CS\out\msysx86\optimize\libs\libcrystalspace.a
@end example

Finally, you have to add the @sc{gdi} library. This can be found
in the MinGW directory. For example:

@example
..\MinGW-3.1.0-1\lib\libgdi32.a
@end example

Next, proceed to the @emph{Directories} tab. In that tab switch to the
@emph{Include Directories} sub-tab and add the following:

@example
..\CS\include\crystalspace
..\CS\include
src
..\cel\include
@end example

The last one should only be added if you plan to use @sc{cel}.

The @file{src} directory is where you will put all source code for your
project. (This is optional, of course.)

This concludes the project settings.

@subsubheading Additional Dynamic Link Libraries

Crystal Space requires a few Dynamic Link Libraries (@sc{dll}'s) so that the
program can run. The @sc{dll}'s that are required depend on what your
application needs but they can be any of the @sc{dll}'s which you find in your
path where you installed the Crystal Space Library package for Windows (the
@file{cs-win32libs} package).  Most commonly the following are at least
required:

@itemize
@item
@file{libz-cs.dll}
@item
@file{libjpeg-cs.dll}
@item
@file{libpng-cs.dll}
@end itemize

You can either copy those dll's manually to the project folder (the place where
the executable will reside), or you can make sure the @sc{dll}'s are in a
standard location mentioned by your @samp{PATH} environment variable, or where
@sc{dll}'s are typically found (e.g. inside the @file{c:\windows} folder, for
instance, though modification of system folders is deprecated and discouraged).

@subsubheading Getting Started

Now that the project is set up it is time to start programming.  As an example,
replace the @file{main.cpp} with the one provided here:

@example
#include <crystalspace.h>
#include "myapp.h"

CS_IMPLEMENT_APPLICATION

int main(int argc, char *argv[])
@{
  MyApp app;
  return app.Main (argc, argv);
@}
@end example

After this, create @file{myapp.h} and @file{myapp.cpp}, which will define the
master @code{MyApp} class for the application. Refer to the other tutorials in
this manual for more information on how to proceed from this point.
@xref{Tutorial Simple}.
