Difference between revisions of "How to build VCMI (Windows/Vcpkg)"

From VCMI Project Wiki
Jump to: navigation, search
(Created page with "= Prerequisites = * HoMM 3 (can be bought at [http://www.gog.com/en/gamecard/heroes_of_might_and_magic_3_complete_edition/ gog.com]) * Microsoft Visual Studio 2017([http://www...")
 
 
(61 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= Prerequisites =
 
= Prerequisites =
* HoMM 3 (can be bought at [http://www.gog.com/en/gamecard/heroes_of_might_and_magic_3_complete_edition/ gog.com])
+
* Windows Vista or newer.
* Microsoft Visual Studio 2017([http://www.visualstudio.com/downloads/download-visual-studio-vs download])
+
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2017] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2019]
 +
* in 2020 still most our developers use VS2017, so you are going to have less problems with it as its more widely used and more maintained.
 
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]
 
* Git or git GUI, for example, SourceTree [http://www.sourcetreeapp.com/download download]
 +
* CMake [https://cmake.org/download/ download]. During install after accepting license agreement make sure to check "Add CMake to the system PATH for all users".
 +
* To unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]
 +
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]
  
= Install dependencies =
+
= Choose directory =
 +
 
 +
Create a directory for VCMI development, eg. '''C:\VCMI'''
 +
We will call this directory as '''[VCMI_DIR]'''
 +
 
 +
'''Warning!''' Replace '''[VCMI_DIR]''' with path you chosen in following commands of this instruction.
  
== Create initial directory ==
+
== How to choose good directory ==
Create a directory for vcpkg development, eg. '''C:\vcpkg'''
 
We will call this directory as '''[VCPKG_DIR]'''
 
  
It is recommended to avoid non-ascii characters in the path to your vcpkg folder. The folder should not be write-protected by system.  
+
It is recommended to avoid non-ascii characters in the path to your working folders. The folder should not be write-protected by system.  
 
Good location:
 
Good location:
* '''C:\vcpkg'''
+
* '''C:\VCMI'''
 
Bad locations:
 
Bad locations:
* '''C:\Users\Michał\vcpkg''' (non-ascii character)
+
* '''C:\Users\Michał\VCMI''' (non-ascii character)
* '''C:\Program Files (x86)\vcpkg''' (write protection)
+
* '''C:\Program Files (x86)\VCMI''' (write protection)
 +
 
 +
= Install dependencies =
 +
 
 +
You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.
  
== Clone vcpkg ==
+
== Option A. Use pre-built Vcpkg ==
 +
So you decide to start using Vcpkg packages pre-built by VCMI team.
  
* open SourceTree
+
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]
* File -> Clone
+
* Please note that as of 2020, this lib wasnt yet updated for vs2019, so for vs2019 you will probaby have to use option B.
* select '''https://github.com/microsoft/vcpkg/''' as source
+
=== Download and unpack archive ===
* select '''[VCPKG_DIR]''' as destination
 
* click '''Clone'''
 
  
== Build vcpkg ==
+
Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases
* Run '''[VCPKG_DIR]/bootstrap-vcpkg.bat'''
 
  
== Build dependencies ==
+
Only download latest version available.
* For 32-bit build run '''[VCPKG_DIR]/vcpkg.exe install minizip:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5:x86-windows ffmpeg:x86-windows'''
+
 
* For 64-bit build run '''[VCPKG_DIR]/vcpkg.exe install minizip:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5:x64-windows ffmpeg:x64-windows'''
+
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit
 +
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit
 +
 
 +
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".
 +
 
 +
=== Move dependencies to target directory  ===
 +
 
 +
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.
 +
 
 +
Move extracted "vcpkg" directory into your '''[VCMI_DIR]'''.
 +
 
 +
== Option B. Build Vcpkg on your own ==
 +
Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.
 +
=== Create initial directory ===
 +
 
 +
=== Clone vcpkg ===
 +
 
 +
# open SourceTree
 +
# File -> Clone
 +
# select '''https://github.com/microsoft/vcpkg/''' as source
 +
# select '''[VCMI_DIR]/vcpkg''' as destination
 +
# click '''Clone'''
 +
 
 +
From command line use:
 +
<pre>
 +
git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg
 +
</pre>
 +
 
 +
=== Build vcpkg ===
 +
* Run
 +
<pre>
 +
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat
 +
</pre>
 +
 
 +
=== Build dependencies ===
 +
* For 32-bit build run:
 +
<pre>
 +
[VCMI_DIR]/vcpkg/vcpkg.exe install sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows smpeg2:x86-windows
 +
</pre>
 +
* For 64-bit build run
 +
<pre>
 +
[VCMI_DIR]/vcpkg/vcpkg.exe install sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows smpeg2:x64-windows
 +
</pre>
  
 
= Build VCMI =
 
= Build VCMI =
  
== Create initial directory ==
+
== Clone VCMI ==
Create a directory for VCMI development, eg. '''C:\VCMI'''
+
# open SourceTree
We will call this directory as '''[VCMI_DIR]'''
+
# File -> Clone
 +
# select '''https://github.com/vcmi/vcmi/''' as source
 +
# select '''[VCMI_DIR]/source''' as destination
 +
# expand Advanced Options and change Checkout Branch to "develop"
 +
# tick Recursive submodules
 +
# click '''Clone'''
 +
 
 +
or From command line use:
 +
<pre>
 +
git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source
 +
</pre>
 +
 
 +
== Generate solution for VCMI ==
 +
# create '''[VCMI_DIR]/build''' folder
 +
# open '''[VCMI_DIR]/build''' in command line:
 +
## Run Command Prompt or Power Shell.
 +
## Execute: cd [VCMI_DIR]/build
 +
# execute one of following commands to generate project
 +
 
 +
'''Visual Studio 2017 - 32-bit build'''
 +
<pre>
 +
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"
 +
</pre>
 +
 
 +
'''Visual Studio 2017 - 64-bit build'''
 +
<pre>
 +
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"
 +
</pre>
 +
 
 +
'''Visual Studio 2019 - 32-bit build'''
 +
<pre>
 +
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A Win32
 +
</pre>
 +
 
 +
'''Visual Studio 2019 - 64-bit build'''
 +
<pre>
 +
cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A x64
 +
</pre>
 +
 
 +
== Compile VCMI with Visual Studio ==
 +
# open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio
 +
# select "Release" build type in combobox
 +
# right click on '''BUILD_ALL''' project - build project. This BUILD_ALL project should be in "CMakePredefinedTargets" tree in Solution Explorer.
 +
# grab VCMI in '''[VCMI_DIR]/build/bin''' folder!
 +
 
 +
== Compile VCMI from command line ==
 +
 
 +
'''For release build'''
 +
<pre>
 +
cmake --build [VCMI_DIR]/build --config Release
 +
</pre>
 +
 
 +
'''For debug build'''
 +
<pre>
 +
cmake --build [VCMI_DIR]/build --config Debug
 +
</pre>
 +
Debug will be used by default even "--config" if not specified.
 +
 
 +
= Create VCMI installer =
 +
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.
 +
 
 +
After you build VCMI execute following commands from '''[VCMI_DIR]/build'''.
 +
=== Execute following if you built for Release: ===
 +
<pre>
 +
cpack
 +
</pre>
 +
=== If you built for Debug: ===
 +
<pre>
 +
cpack -C Debug
 +
</pre>
 +
 
 +
= Troubleshooting and workarounds =
 +
Vcpkg might be very unstable due to limited popularity and fact of using bleeding edge packages (such as most recent Boost). Using latest version of dependencies could also expose both problems in VCMI code or library interface changes that developers not checked yet. So if you're built Vcpkg yourself and can't get it working please try to use binary package.
 +
 
 +
Pre-built version we provide is always manually tested with all supported versions of MSVC for both Release and Debug builds and all known quirks are listed below.
 +
 
 +
=== Debug build of VCMI won't run since SDL2.dll / libbz2.dll missing ===
 +
 
 +
Almost all of Vcpkg debug libraries are built with "d" prefix, but for whatever reason VCMI or some libraries might expect them to be named without prefix. Workaround is to just make a copy of said library with different name.
 +
 
 +
Likely this can be resolved by some CMake configuration magic so if you know how please make pull request.
 +
 
 +
=== I got crash within library XYZ.dll ===
  
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 workaround is to use debug version of said library instead of release one or vice versa. If that's helped you can swap the library within Vcpkg package itself so you don't need to do it every time when you.
Good location:
 
* '''C:\VCMI'''
 
Bad locations:
 
* '''C:\Users\Michał\VCMI''' (non-ascii character)
 
* '''C:\Program Files (x86)\VCMI''' (write protection)
 
  
== Clone VCMI ==
+
=== Debug build is very slow ===
* open SourceTree
 
* File -> Clone
 
* select '''https://github.com/vcmi/vcmi/''' as source
 
* select '''[VCMI_DIR]/source''' as destination
 
* click '''Clone'''
 
  
== Compile VCMI ==
+
Debug builds with MSVC are generally extremely slow since it's not just VCMI binaries are built as debug, but every single dependency too and this usually mean no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary.
* create '''[VCMI_DIR]/build'''
 
* open '''[VCMI_DIR]/build''' in terminal
 
* execute '''cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCPKG_DIR]/scripts/buildsystems/vcpkg.cmake -DCMAKE_INSTALL_PREFIX=[VCMI_DIR]/install'''
 
* open '''VCMI.sln''' in Visual Studio
 
* select "Release" build type in combobox
 
* right click on '''BUILD_ALL''' project - build project
 
* right click on '''INSTALL''' project - build project
 
* grab VCMI in '''[VCMI_DIR]/install''' folder!
 

Latest revision as of 22:55, 6 February 2021

Prerequisites

  • Windows Vista or newer.
  • Microsoft Visual Studio 2017 or 2019
  • in 2020 still most our developers use VS2017, so you are going to have less problems with it as its more widely used and more maintained.
  • Git or git GUI, for example, SourceTree download
  • CMake download. During install after accepting license agreement make sure to check "Add CMake to the system PATH for all users".
  • To unpack pre-build Vcpkg: 7-zip
  • To create installer: NSIS

Choose directory

Create a directory for VCMI development, eg. C:\VCMI We will call this directory as [VCMI_DIR]

Warning! Replace [VCMI_DIR] with path you chosen in following commands of this instruction.

How to choose good directory

It is recommended to avoid non-ascii characters in the path to your working folders. 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)

Install dependencies

You have two options: to use pre-built libraries or build your own. We strongly recommend start with using pre-built ones.

Option A. Use pre-built Vcpkg

So you decide to start using Vcpkg packages pre-built by VCMI team.

Package guaranteed to work since they tested with every commit by AppVeyor

  • Please note that as of 2020, this lib wasnt yet updated for vs2019, so for vs2019 you will probaby have to use option B.

Download and unpack archive

Archives are available from GitHub: https://github.com/vcmi/vcmi-deps-windows/releases

Only download latest version available.

  • vcpkg-export-x86-windows-v140.7z to build for 32-bit
  • vcpkg-export-x64-windows-v140.7z to build for 64-bit

Extract archive by right clicking on it and choosing "7-zip -> Extract Here".

Move dependencies to target directory

Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.

Move extracted "vcpkg" directory into your [VCMI_DIR].

Option B. Build Vcpkg on your own

Be aware that building Vcpkg might take a lot of time depend on your CPU model and 10-20GB of disk space.

Create initial directory

Clone vcpkg

  1. open SourceTree
  2. File -> Clone
  3. select https://github.com/microsoft/vcpkg/ as source
  4. select [VCMI_DIR]/vcpkg as destination
  5. click Clone

From command line use:

git clone https://github.com/microsoft/vcpkg.git [VCMI_DIR]/vcpkg

Build vcpkg

  • Run
[VCMI_DIR]/vcpkg/bootstrap-vcpkg.bat

Build dependencies

  • For 32-bit build run:
[VCMI_DIR]/vcpkg/vcpkg.exe install sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows fuzzylite:x86-windows smpeg2:x86-windows
  • For 64-bit build run
[VCMI_DIR]/vcpkg/vcpkg.exe install sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows fuzzylite:x64-windows smpeg2:x64-windows

Build VCMI

Clone VCMI

  1. open SourceTree
  2. File -> Clone
  3. select https://github.com/vcmi/vcmi/ as source
  4. select [VCMI_DIR]/source as destination
  5. expand Advanced Options and change Checkout Branch to "develop"
  6. tick Recursive submodules
  7. click Clone

or From command line use:

git clone --recursive https://github.com/vcmi/vcmi.git [VCMI_DIR]/source

Generate solution for VCMI

  1. create [VCMI_DIR]/build folder
  2. open [VCMI_DIR]/build in command line:
    1. Run Command Prompt or Power Shell.
    2. Execute: cd [VCMI_DIR]/build
  3. execute one of following commands to generate project

Visual Studio 2017 - 32-bit build

cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"

Visual Studio 2017 - 64-bit build

cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"

Visual Studio 2019 - 32-bit build

cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A Win32

Visual Studio 2019 - 64-bit build

cmake [VCMI_DIR]/source -DCMAKE_TOOLCHAIN_FILE=[VCMI_DIR]/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A x64

Compile VCMI with Visual Studio

  1. open [VCMI_DIR]/build/VCMI.sln in Visual Studio
  2. select "Release" build type in combobox
  3. right click on BUILD_ALL project - build project. This BUILD_ALL project should be in "CMakePredefinedTargets" tree in Solution Explorer.
  4. grab VCMI in [VCMI_DIR]/build/bin folder!

Compile VCMI from command line

For release build

cmake --build [VCMI_DIR]/build --config Release

For debug build

cmake --build [VCMI_DIR]/build --config Debug

Debug will be used by default even "--config" if not specified.

Create VCMI installer

Make sure NSIS is installed to default directory or have registry entry so CMake can find it.

After you build VCMI execute following commands from [VCMI_DIR]/build.

Execute following if you built for Release:

cpack

If you built for Debug:

cpack -C Debug

Troubleshooting and workarounds

Vcpkg might be very unstable due to limited popularity and fact of using bleeding edge packages (such as most recent Boost). Using latest version of dependencies could also expose both problems in VCMI code or library interface changes that developers not checked yet. So if you're built Vcpkg yourself and can't get it working please try to use binary package.

Pre-built version we provide is always manually tested with all supported versions of MSVC for both Release and Debug builds and all known quirks are listed below.

Debug build of VCMI won't run since SDL2.dll / libbz2.dll missing

Almost all of Vcpkg debug libraries are built with "d" prefix, but for whatever reason VCMI or some libraries might expect them to be named without prefix. Workaround is to just make a copy of said library with different name.

Likely this can be resolved by some CMake configuration magic so if you know how please make pull request.

I got crash within library XYZ.dll

Good workaround is to use debug version of said library instead of release one or vice versa. If that's helped you can swap the library within Vcpkg package itself so you don't need to do it every time when you.

Debug build is very slow

Debug builds with MSVC are generally extremely slow since it's not just VCMI binaries are built as debug, but every single dependency too and this usually mean no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary.