4.22.2 Creating an External MSVC 6 Application

Written by Philip Wyett philip.wyett@w-tech.co.uk. Last updated 13 May 2003.

This HOWTO is a step by step guide for creating a basic Crystal Space application with MSVC 6 outside the Crystal Space source tree.

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.

In addition to this written tutorial. You can download zip archive(s) containing video (in avi format) of each step in the tutorial. You can download each video with every step as you progress or download all the videos in a single zip archive via the link below.

All Steps Videos - 4.5Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/all_steps.zip

NOTE: In the videos you will see red and blue stars appear. These are to indicate mouse clicks. Red for a left mouse button click or double click. A blue star appearing indicates a right mouse button click.

Step 1 - Creating a basic project workspace.

Step 1 Video - 0.4Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/step_01.zip

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

Firstly we select the type of application we wish to create. Crystal Space win32 applications primarily work from a console application 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.

Select Win32 Console Application. Now enter the name of your application in the Project 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), which asks what type of console application you would like to create. We are working from a blank canvas, as all Crystal Space application are. Thus we select An empty project. Once done, click on the Finish button.

You should now be presented with a new dialog box (see image below). This dialog is to confirm the previous settings you have supplied during the workspace creation process. Once checked and verified to be correct, click on the OK button.

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

Step 2 - Adding files/code to the workspace.

Step 2 Video - 0.4Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/step_02.zip

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 FileView tab within the Workspace window. See the image below to see the Workspace window from within the MSVC IDE.

To add file(s) to a project workspace, select the appropriate folder in the Workspace window, be that Source Files or Include Files etc. Right click on it to bring up the context menu and then click on Add Files To Folder. You will now be presented with the Insert Files into Project dialog box, which can be seen below.

After selecting the desired file(s) you wish to add, click on the OK 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 Include Files folder. Once done you should have a Workspace window which looks like the image below.

Step 3 - Setting Crystal Space PATHS inside MSVC.

Step 3 Video - 1.02Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/step_03.zip

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.

Click on Directories tab of the Options dialog. 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 an empty area at the bottom of the list in the Directories window. This will open it with a browse button (button with three dots) on the right hand side, enabling you to and select the Crystal Space `include' directory - wherever it is on your system. See the imsge below for an example of it set.

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.

`CS\out\release\libs\'
`CS\out\debug\libs\'

See image below for an example of these set.

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

Step 4 - Setting Preprocessor Definitions in MSVC.

Step 4 Video - 0.9Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/step_04.zip

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 File menu select Projects then Settings.... Alternatively, you can right click on the highlighted area in the Workspace and then click on Settings... - both ways work.

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

Select the C/C++ tab and 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 commas. An example the ones entered for a debug build can be seen in the image below.

Select the C/C++ tab and 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 commas. An example the ones entered for a release build can be seen in the image below.

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

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

Step 5 Video - 0.5Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/step_05.zip

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 File menu select Projects then Settings.... Alternatively, you can right click on the highlighted area in the Workspace and then click on Settings... - both ways work.

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

Select the C/C++ tab and then from the Category drop down menu, 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 Use run-time library drop down menu. As can be seen in the image below.

For release builds you need to select Multithreaded DLL from the Use run-time library drop down menu. As can be seen in the image below.

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

Step 6 - Linking with the Crystal Space libraries.

Step 6 Video - 1.4Mb zip archive download.

ftp://sunsite.dk/projects/crystal/support/msvc/howtos/msvc6_ext_app/step_06.zip

When compiling Crystal Space in release and debug mode, you will end up with the following libraries, 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 library):

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

Crystal Space release library names:

libcrystalspace.lib libcrystalspaceirectx.lib libcrystalspace_opengl.lib libcrystalspace_windows.lib

To add the necessary libraries to link our application. 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 File menu select Projects then Settings.... Alternatively, you can right click on the highlighted area in the Workspace and then click on Settings...-both ways work.

For applications we need only link with the primary Crystal Space library. The other libraries provide support for custom plugin modules. Select the Link tab and in the text box Object/library modules add the Crystal Space library into the box with those already there.

Debug:

libcrystalspace_d.lib

See image below for example of debug build link settings.

Release:

libcrystalspace.lib

See image below for example of release build link settings.

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

Commonly encountered problems.

• Q. I get the following error:

  ----------Configuration: simple1 - Win32 Release---------- Compiling... simple1.cpp C:\CS\INCLUDE\csplatform.h(26) : fatal error C1083: Cannot open include file: 'csconfig.h': No such file or directory Error executing cl.exe. simple1.exe - 1 error(s), 0 warning(s)

  A. Repeat Step 4 - You seem to have not set one or more of the preprocessor definitions correctly.

• Q. I get the following link errors:

  ----------Configuration: simple1 - Win32 Release---------- Compiling... simple1.cpp Linking... simple1.obj : error LNK2001: unresolved external symbol "public: void __thiscall csReversibleTransform::RotateThis( class csVector3 const &,float)" simple1.obj : error LNK2001: unresolved external symbol "public: static struct iSCF * iSCF::SCF" simple1.obj : error LNK2001: unresolved external symbol "public: __thiscall csView::csView( struct iEngine *,struct iGraphics3D *)" simple1.obj : error LNK2001: unresolved external symbol "public: static bool __cdecl csInitializer::OpenApplication( struct iObjectRegistry *)" simple1.obj : error LNK2001: unresolved external symbol "public: static void __cdecl csCommandLineHelper::Help( struct iObjectRegistry *,struct iCommandLineParser *)" simple1.obj : error LNK2001: unresolved external symbol "public: static bool __cdecl csCommandLineHelper::CheckHelp( struct iObjectRegistry *,struct iCommandLineParser *)" simple1.obj : error LNK2001: unresolved external symbol "public: static bool __cdecl csInitializer::SetupEventHandler( struct iObjectRegistry *, bool (__cdecl*)(struct iEvent &),unsigned int)" simple1.obj : error LNK2001: unresolved external symbol "public: static bool __cdecl csInitializer::RequestPlugins( struct iObjectRegistry *,...)" simple1.obj : error LNK2001: unresolved external symbol "bool __cdecl csDefaultRunLoop(struct iObjectRegistry *)" simple1.obj : error LNK2001: unresolved external symbol "public: static void __cdecl csInitializer::DestroyApplication( struct iObjectRegistry *)" simple1.obj : error LNK2001: unresolved external symbol "public: static struct iObjectRegistry * __cdec csInitializer::CreateEnvironment( int,char const * const * const)" simple1.obj : error LNK2001: unresolved external symbol "int __cdecl csPrintf(char const *,...)" simple1.obj : error LNK2001: unresolved external symbol "int __cdecl csPrintfV(char const *,char *)" MSVCRT.lib(crtexe.obj) : error LNK2001: unresolved external symbol _main Release/simple1.exe : fatal error LNK1120: 14 unresolved externals Error executing link.exe. simple1.exe - 15 error(s), 0 warning(s)

  A. This would indicate that you have forgotten to add the Crystal Space static libraries to link with. Work through Step 6 again and re-check the settings you have entered.

• Q. I get the following link errors:

  ----------Configuration: simple1 - Win32 Release---------- Compiling... simple1.cpp Linking... MSVCRT.lib(MSVCRT.dll) : error LNK2005: _strchr already defined in LIBC.lib(strchr.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _strstr already defined in LIBC.lib(strstr.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _tolower already defined in LIBC.lib(tolower.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _strncpy already defined in LIBC.lib(strncpy.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _free already defined in LIBC.lib(free.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _memmove already defined in LIBC.lib(memmove.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _realloc already defined in LIBC.lib(realloc.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _malloc already defined in LIBC.lib(malloc.obj) MSVCRT.lib(MSVCRT.dll) : error LNK2005: _strncmp already defined in LIBC.lib(strncmp.obj) LINK : warning LNK4098: defaultlib "MSVCRT" conflicts with use of other libs; use /NODEFAULTLIB:library Release/simple1.exe : fatal error LNK1169: one or more multiply defined symbols found Error executing link.exe. simple1.exe - 10 error(s), 1 warning(s)

  A. This or similar LNK2005 errors, tend to indicate that you have forgotten to set the correct run-time library in the project settings. Work through Step 5 again and make sure you have your project set to Debug Multithreaded DLL or Multithreaded DLL for debug and release builds respectively.

This document was generated using texi2html 1.76.