Visual C++ on Windows
Getting started
First step is to make sure your Visual Studio system is up to date. As of this writing, the latest service packs are:
- Visual Studio 2008 (9.0) Service Pack 1
- Visual Studio 2005 (8.0) Service Pack 1
- Visual Studio 2003 (7.1) Service Pack 1
- Visual Studio 2002 (7.0) Service Pack 1
- Visual Studio 6.0 Service Pack 6
You also need to install the latest version of DirectX:
If your compiler is old, particular relevant for Visual Studio 6.0 users, you also need to install a recent version of the platform SDK:
If you are using the free Visual Studio Express, you need to normalize your build environment. Codeproject.com got a nice guide for this:
Finally when you are done with tweaking around with your compiler, you need to download the precompiled binaries we've created for you. They save you the trouble of compiling all the ClanLib dependency libraries:
Unfortunately none of our main developers use Visual Studio 6.0 anymore, so if you use that version of Visual Studio you will have to compile the dependency libraries yourself.
After you downloaded the binaries, install these libraries in a directory. Remember which one, because you need to enter that information in the next section.
Preparing installation
The first step in using ClanLib under Windows is to setup a sane build environment. This involves two things:
- ClanLib must be able to locate the libraries it uses.
- ClanLib must know where to install itself.
My personal build environment is setup as follows using c:\Development\Environment as base path:
- c:\Development\Environment\lib contains all .lib files that didn't come along with msvc++ and that are needed by ClanLib.
- c:\Development\Environment\include contains all include files needed by the libs.
(You don't need to follow the same scheme, put your libraries where it fits you)
Here is how it looks like after I've installed Zlib (from the precompiled binaries download or if you built zlib from source):
- c:\Development\Environment\include\zlib.h
- c:\Development\Environment\include\zconf.h
- c:\Development\Environment\lib\zlib-static-mt.lib
- c:\Development\Environment\lib\zlib-static-mt.pdb
- c:\Development\Environment\lib\zlib-static-mt-debug.lib
- c:\Development\Environment\lib\zlib-static-mt-debug.pdb
- c:\Development\Environment\lib\zlib-x64-static-mt.lib
- c:\Development\Environment\lib\zlib-x64-static-mt.pdb
- c:\Development\Environment\lib\zlib-x64-static-mt-debug.lib
- c:\Development\Environment\lib\zlib-x64-static-mt-debug.pdb
The configure wizard tool in ClanLib will prompt you for the paths to the include and lib directories, but generally it is recommended you configure Visual C++ to know where to find these libraries. If you do not, you will have to explicitly add the paths to your applications project files or you will get include errors.
To add the paths to Visual Studio:
- Go through the Tools menu and select Options...
- Open the Projects and Solutions node and pick VC++ Directories
- Select Include Files in the 'Show directories for' combo box. Fill in the include directory (c:\Development\Environment\Include).
- Select Library Files in the combo box. Fill in the libraries directory (c:\Development\Environment\Lib).
Important: If you need to add the DirectX or Platform SDK paths to the VC++ Directories, make sure they are listed on the top of the lists. Otherwise it may find the older versions that may have been distributed with your version of Visual Studio.
Configuring ClanLib
When you initially download a ClanLib source package, it will only include solutions for the ClanLib Configure Wizard:
- configure-vc90.sln (Visual Studio 2008)
- configure-vc80.sln (Visual Studio 2005)
- configure.dsw (Visual Studio 6.0, 2002 and 2003)
You have to compile and run this wizard and answer its questions carefully. Incorrect information will give you problems during the compilation.
When the configure wizard asks me where to install the header and library files, I specify those paths from section 2: C:\Development\Environment\include and C:\Development\Environment\lib.
When this is done, open the ClanLib.dsw file if you are using Developer Studio 6.0, or the ClanLib.sln file if you are using the newer versions.
Important: Make sure you launch the configure wizard from within Visual Studio, since the configure tool expects the current directory to be the root of the ClanLib package. If you launch configure.exe manually from Explorer, the current working directory will be the Debug or Release directory and the configure process will fail.
Compiling ClanLib
After loading the ClanLib solution, the project view will show many different projects; clanApp, clanCore, clanDisplay etc...
Start with making clanCore the active project, if its not active already. You do this by right-clicking it, and select 'Set as Active Project'. Select Debug or Release in the toolbar. If you can't find this option anywhere, right click on the toolbar, and make sure Build is selected, and deselect the Build Minibar. Press F7 to compile the active project.
You need to compile at least these projects:
- clanApp
- clanCore
- clanDisplay
- clanGL
Optionally, you can compile the others if you need them. Menu item Build->Batch Build is handy here.
Each library in ClanLib can be built in multiple different versions. With or without unicode support, x86 or x64, debug or release, static or as a DLL and so on. The version is reflected in the library name:
- clanCore-static-mt.lib: static library, multithreaded runtime, release build
- clanCore-static-mt-debug.lib: static library, multithreaded runtime, debug build
- clanCore-static-mt-uc.lib: static library, multithreaded runtime, unicode, release build
The ClanLib headers automatically detect which version is to be used. This is done by looking at defines set by Visual Studio. For example, the define _DEBUG is set by the compiler when you build debug versions of your application, which causes the ClanLib/core.h header to issue a #pragma comment(lib, "clanCore-static-mt-debug.lib") statement, which makes the linker automatically link with that specific version of the library.
After a successful compilation of ClanLib, it will automatically run a batch file that will install all headers and lib files in the path you specified in the wizard. In my case, that is c:\Development\Environment\lib and c:\Development\Environment\include. So the following files will be added:
c:\Development\Environment\lib\clanCore-static-mt.lib c:\Development\Environment\lib\clanCore-static-mt-debug.lib c:\Development\Environment\lib\clanGL-static-mt.lib c:\Development\Environment\lib\clanGL-static-mt-debug.lib ... c:\Development\Environment\include\ClanLib\core.h c:\Development\Environment\include\ClanLib\gl.h ...
Creating a solution for your application
Follow these steps to create a solution for a ClanLib application under Visual Studio 2005:
- Select File->New...
- Select Projects->Win32 Application, and specify where you want it located.
- Select "An empty project", and press OK till you're finished with the wizard.
- Select Project->Settings...
Notice there are several configurations in which you can modify settings. Normally, these are 'Win32 Debug' and 'Win32 Release'. You switch between these in the 'Settings for:' droplist. In section 6 and 7 below, you need to modify both these settings (sections a for release setting, and sections b for debug settings). - Select the 'C/C++' tab, and then Category 'Code Generation'
- For Release version, change the 'Use run-time library' to Multithreaded.
- For Debug version, change the 'Use run-time library' to Debug Multithreaded.
Follow these steps to create a solution for a ClanLib application under Visual Studio 2008:
- Select File->New...
- Find Visual C++ group in the Project Types, and select Win32 Project, and specify where you want it located, and click OK.
- Under Application Settings, select "Empty project" , and press Finish.
- Add a new c++ file to your project (Add new item->C++ File, or Add class..) (If you do not do this first, you will not see the C++ / Code Generation settings required for step 6).
- Right click your Project (not the solution) and select Properties.
Select the Configuration Properties section.
Notice there are several configurations in which you can modify settings. Normally, these are 'Debug' and 'Release'. You switch between these in the 'Configuration:' droplist. In section 7 and 8 below, you need to modify both these settings (sections a for release setting, and sections b for debug settings). - Select the 'C/C++' tab, and then Category 'Code Generation'
- For Release version, change the 'Use run-time library' to Multithreaded.
- For Debug version, change the 'Use run-time library' to Debug Multithreaded.
Problems?
The most common problems encountered with building ClanLib applications:
-
Problem: You get a lot of linker errors complaining about multiple definitions of functions like _exit
This is almost always caused by mixing runtime versions. Your project is most likely set to Multithreaded Debug DLL, while ClanLib expects it to be Multithreaded Debug. Fixed by going to the project settings of your project and set it to what ClanLib expects.
-
Problem: You are using Visual Studio Express and get a lot of linker errors complaining about missing symbols such as __imp__MessageBoxW@16.
Generally caused by your Visual Studio not linking with the correct default link libraries. To fix this, see the Default Link Libraries sections in the Using the Free Visual C++ 2005 Express Edition to Develop Win32 Applications guide. If this does not fix your problem, look up the function (i.e. MessageBox in the above example) in MSDN and add the appropriate missing library to your linker settings.