Revision as of 22:21, 19 April 2014

Prerequisites

• Installed Heroes3 (can be bought for $10 at gog.com)
• Optionally, you can have also WoG or ERA installed.
• IDE: Microsoft Visual C++ 2013 Express for Desktop. It can be downloaded for free from microsoft.com. Higher editions of Visual Studio (Professional, Premium and Ultimate) are also supported. VCMI can be also built with GCC 4.6+ (using MinGW environment), however it's not covered in this tutorial. We strongly suggest using MSVC on Windows, unless you're an advanced developer (but then you wouldn't need this tutorial :]).
  • Visual Studio 2012 is support is deprecated but still present.
  • Visual Studio 2010 is *not* supported and won't work.
• Git client:
  • Visual Studio 2013 has built-in Git support. It isn't complete, but having most important Git commands integrated in IDE is very convienent. Update 2 brings a few handy features (blame).
  • Visual Studio 2012 [which you shouldn't use anyway] offers similar (though more limited) feature set through official plugin. microsoft.com
  • Because Visual Studio support fir Git is limited, I recommend having installed some else Git client, like TortoiseGit code.google.com
• Libraries pack: download.vcmi.eu. It contains includes and pre-built binaries of several libraries VCMI uses. You DO NOT need to download them separately, they're in the pack. The libraries included are:
  • SDL
  • SDL_image
  • SDL_mixer
  • SDL_TTF
  • zlib
• Boost libraries You can either build them using sources from boost.org (it's very simple, check the instruction below) or download the binaries from [1]. Depending on the version of Visual Studio you use, you'll need:
  • Boost 1.51 or (preferably) newer for Visual Studio 2012,
  • Post-1.55 (you'll need to grab sources from Git) build for Visual Studio 2013.

Preparing place

Initial directory structure and libraries pack

Create a directory for VCMI development, eg. C:\VCMI. Extract there libraries pack. It contains initial directory structure.

It is recommended to avoid non-ascii characters in the path to your VCMI development folder. The folder should not be write-protected by system. Good location:

• C:\VCMI

Bad locations:

• C:\Users\Michał\VCMI (non-ascii character)
• C:\Program Files (x86)\VCMI (write protection)

Obtaining VCMI sources

Using Visual Studio

• Start Visual Studio. Don't load any project.
• Open Team Explorer panel.
• Click the "Connect to Team Projects" icon at the Team Explorer's top bar.
• Make sure that the "Local Git Repositories" node is expanded and click the "Clone" below it.
• Enter the
  • repo address (first field): https://github.com/vcmi/vcmi )
  • the desired path for the repo to be placed. In our example this'll be: C:\VCMI\trunk
• Click clone. Done.

Now you have the local copy of the repository on the disk. It should appear in the Team Explorer under the "Local Git Repositories" section. Double click it and then select a solution to open.

Using TortoiseGit client

(The screenshots are not updated for the Git, however the process is pretty much the same.)

Libraries pack contains default subfolder for VCMI sources named trunk. Right click it and select "Git Clone…" from context menu.

In the dialog type (or paste :]) https://github.com/vcmi/vcmi/ as URL of repository. You should not need to alter other options.

Hit OK and latest VCMI sources will be downloaded from the repository. Double click VCMI_VS11.sln file to open VCMI projects in Visual Studio.

Boost libraries

VCMI depends on the Boost libraries. You can either build them on your own or download the installer.

Using precompiled binaries

Go to http://sourceforge.net/projects/boost/files/boost-binaries/ and enter the latest stable (not beta) build directory. Then download the appropriate version. If you are following the suggested workflow (Visual 2013, 32-bit VCMI build) this would be "boost_1_55_0-msvc-12.0-32.exe" (sic! msvc-12.0 means Visual 2013)

Run the installer. If you chose the default install location, your paths to library are:

• Include path: C:\local\boost_1_55_0
• Library path: C:\local\boost_1_55_0\lib32-msvc-12.0

Building from sources

Boost libraries sources are distributed as an archive file containing single folder named like "boost_1_55_0". Let's assume that you've extracted the archive into C:\C++ folder.

Instructions on how to build Boost are available in the libraries documentation. As for 1.55.0 version it's as simple as typing in the VS2013 x86 Native Tools Command Prompt (look for it in your Start menu; the usual Command Prompt might work as well) the following:

cd "C:\C++\boost_1_55_0"
bootstrap
b2 address-model=32 --toolset=msvc-12.0 --stagedir=./stage32

If you want to build 64-bit version of VCMI issue also

b2 address-model=64 --toolset=msvc-12.0 --stagedir=./stage64

When build is complete (it may take some time), there should exist folder C:\C++\boost_1_55_0\stage32\lib containing numerous *.lib files. It's your Boost library directory. Your Boost include directory will be C:\C++\boost_1_55_0.

Adjusting project files

Adding Boost library folders

All projects are aware of includes/ and libs/ directories in the main VCMI folder. Because libraries package uses them, the only remaining issue is giving IDE information where you have Boost library (the only library not included in the package).

There are several alternative ways to do that:

Global

By following these steps, you'll enable Boost for all your projects in Visual Studio. If you wish to use Boost in your other projects without repeating this setup, this scenario is recommended.

1. Select "expert settings" mode (Tools -> Settings -> Expert Settings). This step may not be needed for Visual Studio editions other then Express.
2. Open Property Pages (View -> Property Pages).
3. In the property manager panel (that just showed up) expand any project and then expand any Win32 configuration within it (Debug or RD). It doesn't make any difference which project and configuration you'll pick, since they all share the one property sheet we're interested in.
4. Double click on Microsoft.Cpp.Win32.user (or r-click it -> Properties). Property window opens.
5. Select "VC++ Directories".
6. Click on "Include Directories" row.
   1. A small button on the right appears. Click it and click on <Edit...>.
   2. Click on "New Line" icon.
   3. Click on "..." batton on the right of textbox that appeared.
   4. Select your Boost include directory (eg. C:\C++\boost_1_55_0). Confirm with OK.
   5. Check if your folder path correrctly appeared on the list. Click OK to save changes and dismiss window.
7. Click on "Library Directories" row. Repeat the steps described for "Include directories", just this time select Boost library directory (eg. C:\C++\boost_1_47_0\stage\lib).
8. Close the property page with OK.

For all VCMI projects

Follow the instructions from previous section with one exception — in step 4. select VCMI_global property sheet.

Individually per project

Add Boost individually for each of the VCMI projects. This is not recommended, since it's most tiresome way.

Open solution explorer. Right click on the project and select "Properties". Follow steps 5 — 8 from "Global" section. Repeat for each project.

Put along with other libs

Project files are pre-configured to use includes/ and libs/ subfolders (that are meant to be next to the trunk folder) during lookup for headers and libs. To make Boost visible to compiler, you can simply copy

• all the boost .lib's (by default from boostfolder/boost_1_x_y/stage/lib) to the libs/ subfolder in your main VCMI directory
• folder "boostfolder/boost_1_x_y/boost" to the includes/ subfolder. Be careful, you need to copy "boost" folder, not its contents!

Compiling

Now you should be able to successfully build VCMI. Select "Build solution" from "Build" menu or press F7. Wait until the compilation finishes.

You should finally see ========== Build: 8 succeeded, 0 failed, 0 up-to-date, 0 skipped ========== message in the IDE output. Built VCMI binaries will be put in the solution folder (C:\VCMI\trunk in our example). If you want to run VCMI somewhere else, open each project properties and adjust "Output Directory" in "General Properties" tab.

Remember that VCMI_client.exe, VCMI_client.dll and VCMI_server.exe need to be in the same directory and AI (GeniusAI.dll) must be in AI/ subfolder.

Running and debugging VCMI

After compilation you should have received new VCMI binaries in your trunk/ folder:

• VCMI_client.exe
• VCMI_server.exe
• VCMI_lib.dll
• GeniusAI.dll (in trunk/AI/ subfolder)
• StupidAI.dll (in trunk/AI/ subfolder)

Running VCMI in a build place (recommended)

VCMI files

Extract package with latest VCMI release to the trunk folder. It contains some content (fonts, graphics, etc) that are not part of SVN repository. Do NOT overwrite anything. Files from repository are always most up-to-date and have priority over the ones released some time ago. If you overwrite any file from SVN you can always use Revert command from TortoiseSVN.

H3 files

VCMI needs files with content from H3. Copy:

• From the game folder:
  • MP3 folder with its contents
  • binkw32.dll
  • smackw32.dll
• From Data subfolder:
  • VIDEO.VID
  • Heroes3.snd
  • h3sprite.lod
  • h3bitmap.lod
  • H3ab_bmp.lod
  • H3ab_ahd.snd
  • H3ab_ahd.vid

You'll also may want to copy some (or all) maps.

VCMI should be smart enough to give meaningful error message when one of content files is missing. Check the console output or VCMI_client_log.txt if something goes wrong.

Libraries

Additionally, you need to copy all *.dll files from libraries pack (libs/x86) to the trunk folder (or your destination folder of choice).

Running VCMI in external folder

Alternatively, you can simply replace binaries in existing VCMI installation with the ones you've built. In such case you should also replace .txt files in config/ directory with the ones from trunk (and any other relevant files that have changed in SVN).

It's not very convenient because you need to copy files each time after build. To avoid that necessity you can change Output Directory in properties of all projects. Then binaries you built will be automatically put in the right place. However you would still need to remember about changes in config files. (Some script for copying them used as post-built event may be a good idea here)

Running / debugging VCMI from IDE

Visual Studio offers several convenient commands to run / debug project. Before you can use them, you need to set Working Directory to $(OutDir) in project properties for VCMI_client.

Now you can start debugging by:

• Using Start Debugging (F5) command - starts game with debugger attached
• Using Step Over/Into (F10 or F11) command - starts game and stops at the beginning of main function, allowing line-by-line execution
• Running VCMI normally and attaching debugger to its process

To debug server, you need to attach to its process before it crashes; otherwise you will just see an information that server has crashed. No breakpoints in its code will be hit. However, in Visual Studio Professional or higher there is possibility to attach to server after is crashes.

Further help

If you need any further help, ask at our forums.