[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.20.2 Creating an External MSVC 7, 7.1 or 8 Application

Originally written by Philip Wyett philipwyett@blueyonder.co.uk. Last updated 20 January 2006.

This HOWTO is a step by step guide for creating a basic Crystal Space application with MSVC 7 (.NET 2002), 7.1 (.NET 2003) or 8 (.NET 2005) outside the Crystal Space source tree.

Note: This text was initially written with only MSVC 7 in mind, consequently, the screenshots are from that version. However, its successors, versions 7.1 and 8, are, in the aspects relevant to this HOWTO, very similar to version 7. Hence, the instructions herein should be easily applicable to those versions as well. If there is a setting that needs to be different for different MSVC versions, the text will explicitly state that.

IMPORTANT: This tutorial assumes you have a basic familiarity with MSVC and it's inner workings. This tutorial also assumes you have a fully compiled (both release and debug) version of Crystal Space somewhere on your computer.

Step 1 - Creating a basic project solution.

Start MSVC and from the File menu click on File then New and once the sub menu of New opens, click on Project. You will now be presented with a dialog box (see image below) for creating a new project.

usingcs/ownprojects/msvc7proj/snap0

Firstly we need to select the type of project we wish to create. Crystal Space applications are Win32 applications and primarily work from a console base. This still allows the creation of Graphical User Interface (GUI) applications. However, it also allows you to use the -console command line switch and access more verbose runtime data normally only available with debug builds. If you do wish to create standard win32 applications, you may do so. However... the -console switch will not operate correctly in that type of application.

In the Project Types: window select Visual C++ projects. Next we move to the Templates: window and choose the application type we wish to create. As mentioned above Crystal Space applications are Win32 applications. So, search that window and select Win32 Project. Now enter the name of your application in the Name text box. In our example, the application will be named `simple1'. Once done, click on the OK button.

You will now be presented with another dialog box (see image below).

usingcs/ownprojects/msvc7proj/snap1

We wish to specify some application settings. So, click on hyperlink text Application Settings below Overview and you will be presented with what can be seen in the screenshot below.

usingcs/ownprojects/msvc7proj/snap2

As discussed above, Crystal Space applications are primarily console based (though GUI are allowed) inorder to give us acces to the verbose diagnostic text via -console. Under Application type:, select Console application. We are starting from a blank canvas. So, in the Additional options: section, check the box Empty project. Once done, click on the Finish button.

You should now be in the MSVC IDE (Intergrated Development Environment), with the simple1 project loaded. Lets move on...

Step 2 - Adding files/code to the project solution.

Rather than create code for this tutorial and keeping inline with time honored tradition - We are now going to cheat and use existing Crystal Space code. :-)

Firstly copy and paste the `simple1.cpp' and `simple1.h' from the Crystal Space code tree, into the newly created `simple1' project directory. These files can be found here:

`CS\apps\tutorial\simple1\'

Once done, return to the MSVC IDE and select the Solution Explorer tab within the Solution Explorer window. See the image below to see the Solution Explorer window from within the MSVC IDE.

usingcs/ownprojects/msvc7proj/snap3

To add file(s) to a project, select the appropriate folder in the Solution Explorer window, be that Source Files or Header Files etc. Right click on it to bring up the context menu and then hover over Add until the sub menu appears and then click on Add Existing Item.... You will now be presented with the Add Existing Item dialog box, which can be seen in the image below.

usingcs/ownprojects/msvc7proj/snap4

After selecting the desired file(s) you wish to add, click on the Open button to finalize your choice(s) and be returned back to the MSVC IDE. Repeat this process twice adding `simple1.cpp' to the Source Files folder and `simple1.h' to the Header Files folder. Once done you should have a Solution Explorer window which looks like the image below.

usingcs/ownprojects/msvc7proj/snap5

Step 3 - Setting Crystal Space PATHS inside MSVC.

First thing we need todo is point MSVC to both Crystal Spaces `include' and both the release and debug build `libs' directories, so it may access them at compile/link time. Select Tools from the File menu and then Options... You will now be presented with the Options dialog box, which can be seen below.

usingcs/ownprojects/msvc7proj/snap6

Click Projects folder of the Options dialog. Now click on VC++ Directories.

usingcs/ownprojects/msvc7proj/snap7

Lets first add the path to the location of the Crystal Space `include' directory. Select Include files in the Show directories for drop down menu. Next click on the New Line button (folder beneath the drop down menu). Click the browse button (button with three dots) on the right hand side, enabling you to select the Crystal Space include directory - wherever it is on your system. See the image below for an example of it set.

usingcs/ownprojects/msvc7proj/snap8

To set the paths to the Crystal Space lib files, you must remember you need to add two--one pointing to the location where the release libs are and another to where the debug libs are located. In the Show directories for drop down menu, now select Library files. Follow the same browse and selection procedure as you used when adding the `include' path, adding the following paths - adjusting for where you have Crystal Space located on your system as well as the MSVC version number you compiled with. Here it was version 7; for versions 7.1 you need to use `out\release71\libs\' and `out\debug71\libs\', likewise for version 8 you need `out\release8\libs\' and `out\debug8\libs\'.

`CS\out\release7\libs\'
`CS\out\debug7\libs\'

See image below for an example of this set.

usingcs/ownprojects/msvc7proj/snap9

Once done, click on the OK button and return to the MSVC IDE.

Step 4 - Setting Preprocessor Definitions in MSVC.

Crystal Space essentially has three preprocessor definitions which MUST be set in-order to successfully compile and link your application. They are `CS_WIN32_CSCONFIG', which is added whether the build is release or debug. `__CRYSTAL_SPACE__', which is also set whether the build is release or debug. And finally `CS_RELEASE' or `CS_DEBUG', which is added as you may guess `CS_RELEASE' in the settings for release builds and `CS_DEBUG' in the settings for debug builds.

To set the preprocessor definitions for your project. Select your project in the Workspace window. See area highlighted in blue in the image below. Now, from the Project menu select Properties. Alternatively, you can right click on the highlighted area in the Workspace and then click on Properties - both ways work.

usingcs/ownprojects/msvc7proj/snap5

Once you have clicked on Properties. You will then be presented with the Properties dialog box, which can be seen in the image below.

usingcs/ownprojects/msvc7proj/snap10

Open the C/C++ folder and select Preprocessor. Insert the appropriate definitions in the Preprocessor Definitions text box i.e. for a debug build `CS_WIN32_CSCONFIG', `__CRYSTAL_SPACE__' and `CS_DEBUG', making sure to separate with semi-colons. Alternatively, you can click the elipsis (...) button to pull up an easier view. An example of the ones entered for a debug build can be seen in the image below.

usingcs/ownprojects/msvc7proj/snap11

Open the C/C++ folder and select Preprocessor. Insert the appropriate definitions in the Preprocessor Definitions text box i.e. for a release build `CS_WIN32_CSCONFIG', `__CRYSTAL_SPACE__' and `CS_RELEASE', making sure to separate with semi-colons. Alternatively, you can click the elipsis (...) button to pull up an easier view. An example the ones entered for a release build can be seen in the image below.

usingcs/ownprojects/msvc7proj/snap12

Once done, click on the OK button and return to the MSVC MSVC IDE.

Step 5 - Setting Run-Time Library Used with Crystal Space Applications.

As in step 4 we need to change one or more project settings. Select your project in the Workspace window. See area highlighted in blue in the image below. Now, from the Project menu select Properties. Alternatively, you can right click on the highlighted area in the Workspace and then click on Properties - both ways work.

usingcs/ownprojects/msvc7proj/snap5

Once you have clicked on Properties, you will be presented with the Properties dialog box once again.

Open the C/C++ folder and select Code Generation. Crystal Space uses the Multithreaded DLL run-time internally, so to avoid conflict and errors applications should use the same.

For debug builds you need to select Debug Multithreaded DLL from the Runtime Library drop down menu. As can be seen in the image below.

usingcs/ownprojects/msvc7proj/snap13

For release builds you need to select Multithreaded DLL from the Runtime Library drop down menu. As can be seen in the image below.

usingcs/ownprojects/msvc7proj/snap14

Once done, click on the OK button and return to the MSVC IDE.

Step 6 - Linking with the Crystal Space libraries.

When compiling Crystal Space in release and debug mode, you will end up with the following static libs, some of which you may require at some point in your own applications if you use the functionality contained within a given library.

Crystal Space debug library names (the _d indicates a debug CS library):

libcrystalspace_d.lib libcrystalspace_directx_d.lib libcrystalspace_opengl_d.lib libcrystalspace_windows_d.lib

Crystal Space release library names:

libcrystalspace.lib libcrystalspace_directx.lib libcrystalspace_opengl.lib libcrystalspace_windows.lib

To add the necessary libraries to link our application. If you are unsure which libraries to take, using only `libcrystalspace(_d).lib' is sufficient in most cases. As in step 4 we need to change one or more project settings. Select your project in the Workspace window. See area highlighted in blue in the image below. Now, from the Project menu select Properties. Alternatively, you can right click on the highlighted area in the Workspace and then click on Properties - both ways work.

usingcs/ownprojects/msvc7proj/snap5

For applications we need only link with the primary Crystal Space library. The other libraries provide support for custom plugin modules. Open the Linker folder and select Input. In the text box Additional Dependencies add the Crystal Space libraries as named below into the box with those already there.

Debug:

libcrystalspace_d.lib

See image below for example of debug build link settings.

usingcs/ownprojects/msvc7proj/snap15

Release:

libcrystalspace.lib

See image below for example of release build link settings.

usingcs/ownprojects/msvc7proj/snap16

Finally, click on OK to return to the MSVC IDE and then build the project.

Commonly encountered problems.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated using texi2html 1.76.