<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Visual C++ on Windows - ClanLib SDK</title>
<link rel="stylesheet" media="screen" type="text/css" href="clanlib.css"/>
<link rel="icon" href="gfx/favicon.png" type="image/png"/>
</head>
<body>
<div id="content">
<h1><a href="."><img src="gfx/clanlib.png" alt="ClanLib SDK" /></a></h1>
<!--
<div style="float: right;">
<a href="download.html">Download</a> :
<a href="docs.html">Documentation</a> :
<a href="development.html">Development</a> :
<a href="donations.html">Donations</a> :
<a href="http://www.rtsoft.com/clanlib">Forum</a> :
<a href="contributions.html">Contributions</a>
</div>
-->
<h2>
<img src="gfx/overview.png"/>Visual C++ on Windows
</h2>
<h3>Getting started</h3>
<p>First step is to make sure your Visual Studio system is up to date. As of
this writing, the latest service packs are:</p>
<ul>
<li><a href="http://msdn.microsoft.com/en-us/vstudio/products/cc533447.aspx">Visual
Studio 2008 (9.0) Service Pack 1</li>
<li><a href="http://msdn2.microsoft.com/en-us/vstudio/bb265237.aspx">Visual
Studio 2005 (8.0) Service Pack 1</li>
<li><a href="http://www.microsoft.com/downloads/details.aspx?familyid=69d2219f-ce82-46a5-8aec-072bd4bb955e&displaylang=en">
Visual Studio 2003 (7.1) Service Pack 1</li>
<li><a href="http://www.microsoft.com/downloads/details.aspx?familyid=c41d8159-b42f-4d06-a797-e510494976ee&displaylang=en">
Visual Studio 2002 (7.0) Service Pack 1</li>
<li><a href="http://msdn2.microsoft.com/en-us/vstudio/aa718364.aspx">
Visual Studio 6.0 Service Pack 6</a></li>
</ul>
<p>You also need to install the latest version of DirectX:</p>
<ul>
<li><a href="http://www.microsoft.com/downloads/details.aspx?familyid=09F7578C-24AA-4E0A-BF91-5FEC24C8C7BF&displaylang=en">
February 2007 DirectX SDK</a></li>
</ul>
<p>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:</p>
<ul>
<li><a href="http://www.microsoft.com/downloads/details.aspx?familyid=C2B1E300-F358-4523-B479-F53D234CDCCF&displaylang=en">
Windows SDK for Windows Vista</a></li>
</ul>
<p>If you are using the free Visual Studio Express, you need to normalize
your build environment. Codeproject.com got a nice guide for this:</p>
<ul><li><a
href="http://www.codeproject.com/useritems/FreeVS2005Win32.asp">Using the
Free Visual C++ 2005 Express Edition to Develop Win32 Applications</a></li>
</ul>
<p>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:</p>
<ul>
<li><a href="http://clanlib.org/download-binaries-win32-vc80.html">Visual
Studio 2005/2008 binaries</a></li>
<li><a href="http://clanlib.org/download-binaries-win32-vc70.html">Visual
Sutdio 2002 and 2003 binaries</a></li>
</ul>
<p>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.</p>
<p>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.</p>
<h3>Preparing installation</h3>
<p>The first step in using ClanLib under Windows is to setup a sane build
environment. This involves two things:</p>
<ol>
<li>ClanLib must be able to locate the libraries it uses.</li>
<li>ClanLib must know where to install itself.</li>
</ol>
<p>My personal build environment is setup as follows using
<span class="code">c:\Development\Environment</span>
as base path:</p>
<ul>
<li><span class="code">c:\Development\Environment\lib</span> contains all .lib files that didn't come along with
msvc++ and that are needed by ClanLib.</li>
<li><span class="code">c:\Development\Environment\include</span> contains all include files needed by the
libs.</li>
</ul>
<p>(You don't need to follow the same scheme, put your libraries
where it fits you)</p>
<p>Here is how it looks like after I've installed Zlib (from the precompiled
binaries download or if you built zlib from source):</p>
<ul>
<li>c:\Development\Environment\include\zlib.h</li>
<li>c:\Development\Environment\include\zconf.h</li>
<li>c:\Development\Environment\lib\zlib-static-mt.lib</li>
<li>c:\Development\Environment\lib\zlib-static-mt.pdb
<li>c:\Development\Environment\lib\zlib-static-mt-debug.lib
<li>c:\Development\Environment\lib\zlib-static-mt-debug.pdb
<li>c:\Development\Environment\lib\zlib-x64-static-mt.lib
<li>c:\Development\Environment\lib\zlib-x64-static-mt.pdb
<li>c:\Development\Environment\lib\zlib-x64-static-mt-debug.lib
<li>c:\Development\Environment\lib\zlib-x64-static-mt-debug.pdb
</ul>
<p>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.</p>
<p>To add the paths to Visual Studio:</p>
<ul>
<li>Go through the Tools menu and select Options...</li>
<li>Open the Projects and Solutions node and pick VC++ Directories</li>
<li>Select Include Files in the 'Show directories for' combo box. Fill in the include directory (<span
class="code">c:\Development\Environment\Include</span>).</li>
<li>Select Library Files in the combo box. Fill in the libraries directory (<span
class="code">c:\Development\Environment\Lib</span>).</li>
</ul>
<p><b>Important</b>: If you need to add the DirectX or Platform SDK paths to the VC++
Directories, make sure they are listed on the <i>top</i> of the lists.
Otherwise it may find the older versions that may have been distributed with
your version of Visual Studio.</p>
<h3>Configuring ClanLib</h3>
<p>When you initially download a ClanLib source package, it will only
include solutions for the ClanLib Configure Wizard:</p>
<ul>
<li>configure-vc90.sln (Visual Studio 2008)</li>
<li>configure-vc80.sln (Visual Studio 2005)</li>
<li>configure.dsw (Visual Studio 6.0, 2002 and 2003)</li>
</ul>
<p>You have to compile and run this wizard and answer its questions carefully.
Incorrect information will give you problems during the compilation.</p>
<p>When the configure wizard asks me where to install the header and library
files, I specify those paths from section 2: <span
class="code">C:\Development\Environment\include</span> and <span
class="code">C:\Development\Environment\lib</span>.</p>
<p>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.</p>
<p><b>Important:</b> 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.</p>
<h3>Compiling ClanLib</h3>
<p>After loading the ClanLib solution, the project view will show many different
projects; clanApp, clanCore, clanDisplay etc...</p>
<p>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.</p>
<p>You need to compile at least these projects:</p>
<ul>
<li>clanApp</li>
<li>clanCore</li>
<li>clanDisplay</li>
<li>clanGL</li>
</ul>
<p>Optionally, you can compile the others if you need them. Menu item
Build->Batch Build is handy here.</p>
<p>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:</p>
<ul>
<li>clanCore-static-mt.lib: static library, multithreaded runtime, release
build</li>
<li>clanCore-static-mt-debug.lib: static library, multithreaded runtime,
debug build
<li>clanCore-static-mt-uc.lib: static library, multithreaded runtime,
unicode, release build</li>
</ul>
<p>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 <span class="code">_DEBUG</span> is set by the compiler when you
build debug versions of your application, which causes the <span
class="code">ClanLib/core.h</span> header to issue a <span
class="code">#pragma comment(lib, "clanCore-static-mt-debug.lib")</span>
statement, which makes the linker automatically link with that specific
version of the library.</p>
<p>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 <span
class="code">c:\Development\Environment\lib</span> and <span
class="code">c:\Development\Environment\include</span>. So the following files will be
added:</p>
<pre>
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
...
</pre>
<!--
<h3>Testing ClanLib</h3>
<p>To have a look at some examples of various parts of ClanLib, open the
Examples.dsw/.sln file in your ClanLib root directory. This was created after
you ran the Configure application.</p>
<p>Select any example, and compile it. You'll find examples covering most
parts of the ClanLib API.</p>
<p>Once you're done and ready for some coding, proceed to next section.</p>
-->
<!--
<h3>Creating applications with ClanLib</h3>
<p>Note that MSVC will know what .lib file to link into your application, based
upon the ClanLib headers you include in your application.</p>
<p>Example:</p>
<p>
If you include <ClanLib/core.h> then depending on whether you are
building release or debug binaries the clanCore.lib or clanCored.lib
library will be automatically linked into your executable.
</p>
-->
<h3>Creating a solution for your application</h3>
<p>Follow these steps to create a solution for a ClanLib application
under Visual Studio 2005:</p>
<ol>
<li> Select File->New...</li>
<li> Select Projects->Win32 Application, and specify where you want it
located.</li>
<li> Select "An empty project", and press OK till you're finished with the
wizard.</li>
<li> Select Project->Settings...<br>
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).</li>
<li> Select the 'C/C++' tab, and then Category 'Code Generation'</li>
<li> For Release version, change the 'Use run-time library' to
Multithreaded.</li>
<li> For Debug version, change the 'Use run-time library' to Debug
Multithreaded.</li>
</ol>
<p>Follow these steps to create a solution for a ClanLib application
under Visual Studio 2008:</p>
<ol>
<li> Select File->New...</li>
<li> Find Visual C++ group in the Project Types, and select Win32 Project,
and specify where you want it located, and click OK.</li>
<li> Under Application Settings, select "Empty project" , and press Finish.</li>
<li> 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).
<li> Right click your Project (not the solution) and select Properties.<br>
Select the Configuration Properties section.<br>
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).</li>
<li> Select the 'C/C++' tab, and then Category 'Code Generation'</li>
<li> For Release version, change the 'Use run-time library' to
Multithreaded.</li>
<li> For Debug version, change the 'Use run-time library' to Debug
Multithreaded.</li>
</ol>
<!--
<li> Select Project->Add To Project->New...</li>
<li> Select C++ Source File, and enter a name for the file, for example 'app.cpp'</li>
<li> Enter a skeleton for your code:
<pre>
#include <ClanLib/core.h>
#include <ClanLib/application.h>
#include <ClanLib/display.h>
#include <ClanLib/gl.h>
class MyApp : public CL_ClanApplication
{
public:
virtual int main(int argc, char **argv)
{
// Create a console window for text-output if not available
// Use printf or cout to display some text in your program
CL_ConsoleWindow console("Console");
console.redirect_stdio();
try
{
// Initialize ClanLib base components
CL_SetupCore setup_core;
// Initialize the ClanLib display component
CL_SetupDisplay setup_display;
// Initialize the ClanLib GL component
CL_SetupGL setup_gl;
// Create a display window
CL_DisplayWindow window("ClanLib application", 640, 480);
// Run until someone presses escape
while (!CL_Keyboard::get_keycode(CL_KEY_ESCAPE))
{
// Clear the display in a dark blue nuance
// The four arguments are red, green, blue and alpha (defaults to 255)
// All color nuances in ClanLib are measured in the interval 0->255
CL_Display::clear(CL_Color(0, 0, 50));
// Flip the display (using a double-buffer),
// showing on the screen what we have drawed
// since last call to flip()
CL_Display::flip();
// This call updates input and performs other "housekeeping"
// Call this each frame
// Also, gives the CPU a rest for 10 milliseconds to catch up
CL_System::keep_alive(10);
}
}
// Catch any errors from ClanLib
catch (CL_Error err)
{
// Display the error message
std::cout << err.message.c_str() << std::endl;
}
// Display console close message and wait for a key
console.display_close_message();
return 0;
}
} app;
</pre></li>
-->
<h3>Problems?</h3>
<p>The most common problems encountered with building ClanLib
applications:</p>
<ol>
<li>
<p><b>Problem</b>: You get a lot of linker errors complaining about multiple
definitions of functions like <span class="code">_exit</span></p>
<p>This is almost always caused by mixing runtime versions. Your project is
most likely set to <span class="code">Multithreaded Debug DLL</span>, while
ClanLib expects it to be <span class="code">Multithreaded Debug</span>.
Fixed by going to the project settings of your project and set it to what
ClanLib expects.</p>
</li>
<li>
<p><b>Problem</b>: You are using Visual Studio Express and get a lot of
linker errors complaining about missing symbols such as <span
class="code">__imp__MessageBoxW@16</span>.</p>
<p>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 <a
href="http://www.codeproject.com/useritems/FreeVS2005Win32.asp">Using the
Free Visual C++ 2005 Express Edition to Develop Win32 Applications</a>
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.</p>
</li>
</ol>
</div>
</body>
</html>
