Compilation Guide - ClanLib SDK
Description: ClanLib is a cross platform C++ toolkit library with focus on games

# Compilation Guide

## Preparing installation

The first step is to download ClanLib and all its dependency libraries. Get the latest source version of ClanLib.

You will need to setup a sane build environment. This involves two things:

1. ClanLib must be able to locate the libraries it uses.
2. 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\win32 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.

Note: 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\win32\zlib-static-mt.lib
- c:\Development\Environment\lib\win32\zlib-static-mt.pdb
- c:\Development\Environment\lib\win32\zlib-static-mt-debug.lib
- c:\Development\Environment\lib\win32\zlib-static-mt-debug.pdb

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\win32).

## Configuring ClanLib

When you initially download a ClanLib source package, it will not contain the ClanLib project files, but rather a Configuration Wizard called configure.exe.

You have to 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.sln solution file.

## 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, 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

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\win32\clanCore-static-mt.lib c:\Development\Environment\lib\win32\clanCore-static-mt-debug.lib c:\Development\Environment\lib\win32\clanGL-static-mt.lib c:\Development\Environment\lib\win32\clanGL-static-mt-debug.lib ... c:\Development\Environment\include\ClanLib\core.h c:\Development\Environment\include\ClanLib\gl.h ...

## Next step

To create a Visual Studio solution file for your project, read the Visual C++ on Windows guide.