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

From VCMI Project Wiki
Jump to: navigation, search
(Avoid entries spam in Contents)
(Information that creating installer is not mandatory)
 
(52 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
= Prerequisites =
 
= Prerequisites =
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2015] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2017]
+
* Windows Vista or newer.
 +
* Microsoft Visual Studio [https://www.visualstudio.com/vs/older-downloads/ 2017] or [http://www.visualstudio.com/downloads/download-visual-studio-vs 2019]
 +
* CI use VS2019, so you are going to have less problems with it.
 
* 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]
+
* 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 unpack pre-build Vcpkg: [http://www.7-zip.org/download.html 7-zip]
 
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]
 
* To create installer: [http://nsis.sourceforge.net/Main_Page NSIS]
 +
 +
= Choose directory =
 +
 +
Create a directory for VCMI development, eg. '''C:\VCMI'''
 +
We will call this directory '''%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 =
 
= Install dependencies =
== Download pre-built Vcpkg ==
 
You might save a time by using Vcpkg packages pre-built by VCMI team.
 
  
Package guaranteed to work since they tested with every commit by [https://ci.appveyor.com/project/vcmi/vcmi AppVeyor]
+
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 [https://github.com/vcmi/vcmi/actions GitHub Actions].
 
=== Download and unpack archive ===
 
=== Download and unpack archive ===
  
Line 18: Line 38:
 
Only download latest version available.
 
Only download latest version available.
  
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit
+
* vcpkg-export-'''x86'''-windows-v140.7z to build for 32-bit no debug, 3 times smaller file size
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit
+
* vcpkg-export-'''x64'''-windows-v140.7z to build for 64-bit no debug, 3 times smaller file size
 +
* vcpkg-export-'''x86'''-windows-v140-debug.7z to build for 32-bit with debug configuration available
 +
* vcpkg-export-'''x64'''-windows-v140-debug.7z to build for 64-bit with debug configuration available
  
 
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".
 
Extract archive by right clicking on it and choosing "7-zip -> Extract Here".
Line 27: Line 49:
 
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.
 
Once extracted "vcpkg" directory will appear with "installed" and "scripts" inside it.
  
Move it where you wish, e.g right to the C:\ so full path to Vcpkg will be '''C:\vcpkg'''. We will call this directory as '''[VCPKG_DIR]'''
+
Move extracted "vcpkg" directory into your '''%VCMI_DIR%'''.
 +
 
 +
== Option B. Build Vcpkg on your own ==
 +
Please be aware that if you're running 32-bit Windows version, then this is impossible due to https://github.com/microsoft/vcpkg/issues/26036
  
== 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.
 
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 ===
 
=== Create initial 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.
 
Good location:
 
* '''C:\vcpkg'''
 
Bad locations:
 
* '''C:\Users\Michał\vcpkg''' (non-ascii character)
 
* '''C:\Program Files (x86)\vcpkg''' (write protection)
 
  
 
=== Clone vcpkg ===
 
=== Clone vcpkg ===
  
* open SourceTree
+
# open SourceTree
* File -> Clone
+
# File -> Clone
* select '''https://github.com/microsoft/vcpkg/''' as source
+
# select '''https://github.com/microsoft/vcpkg/''' as source
* select '''[VCPKG_DIR]''' as destination
+
# select '''%VCMI_DIR%/vcpkg''' as destination
* click '''Clone'''
+
# click '''Clone'''
 +
 
 +
From command line use:
 +
<pre>
 +
git clone https://github.com/microsoft/vcpkg.git %VCMI_DIR%/vcpkg
 +
</pre>
  
 
=== Build vcpkg ===
 
=== Build vcpkg ===
 
* Run  
 
* Run  
 
<pre>
 
<pre>
[VCPKG_DIR]/bootstrap-vcpkg.bat
+
%VCMI_DIR%/vcpkg/bootstrap-vcpkg.bat
 
</pre>
 
</pre>
  
Line 59: Line 79:
 
* For 32-bit build run:
 
* For 32-bit build run:
 
<pre>
 
<pre>
[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 fuzzylite:x86-windows
+
%VCMI_DIR%/vcpkg/vcpkg.exe install tbb:x64-windows fuzzylite:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer[mpg123]:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows luajit:x64-windows
 
</pre>
 
</pre>
 
* For 64-bit build run
 
* For 64-bit build run
 
<pre>
 
<pre>
[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 fuzzylite:x64-windows
+
%VCMI_DIR%/vcpkg/vcpkg.exe install install tbb:x86-windows fuzzylite:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer[mpg123]:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows luajit:x86-windows
 
</pre>
 
</pre>
 +
 +
For the list of the packages used you can also consult [https://github.com/vcmi/vcmi-deps-windows vcmi-deps-windows readme] in case this article gets outdated a bit.
  
 
= 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'''
  
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.
+
or From command line use:
Good location:
+
<pre>
* '''C:\VCMI'''
+
git clone --recursive https://github.com/vcmi/vcmi.git %VCMI_DIR%/source
Bad locations:
+
</pre>
* '''C:\Users\Michał\VCMI''' (non-ascii character)
 
* '''C:\Program Files (x86)\VCMI''' (write protection)
 
 
 
== Clone VCMI ==
 
* open SourceTree
 
* File -> Clone
 
* select '''https://github.com/vcmi/vcmi/''' as source
 
* select '''[VCMI_DIR]/source''' as destination
 
* click '''Clone'''
 
  
 
== Generate solution for VCMI ==
 
== Generate solution for VCMI ==
* create '''[VCMI_DIR]/build'''
+
# create '''%VCMI_DIR%/build''' folder
* open '''[VCMI_DIR]/build''' in terminal
+
# open '''%VCMI_DIR%/build''' in command line:
* execute command to generate project for:
+
## Run Command Prompt or Power Shell.
 +
## Execute: cd %VCMI_DIR%/build
 +
# execute one of following commands to generate project
  
```Visual Studio 2015 - 32-bit build```
+
'''Visual Studio 2017 - 32-bit build'''
 
<pre>
 
<pre>
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCPKG_DIR]/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015"
+
cmake %VCMI_DIR%/source -DCMAKE_TOOLCHAIN_FILE=%VCMI_DIR%/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"
 
</pre>
 
</pre>
  
```Visual Studio 2015 - 64-bit build```
+
'''Visual Studio 2017 - 64-bit build'''
 
<pre>
 
<pre>
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCPKG_DIR]/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 14 2015 Win64"
+
cmake %VCMI_DIR%/source -DCMAKE_TOOLCHAIN_FILE=%VCMI_DIR%/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"
 
</pre>
 
</pre>
  
```Visual Studio 2017 - 32-bit build```
+
'''Visual Studio 2019 - 32-bit build'''
 
<pre>
 
<pre>
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCPKG_DIR]/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017"
+
cmake %VCMI_DIR%/source -DCMAKE_TOOLCHAIN_FILE=%VCMI_DIR%/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A Win32
 
</pre>
 
</pre>
  
```Visual Studio 2017 - 64-bit build```
+
'''Visual Studio 2019 - 64-bit build'''
 
<pre>
 
<pre>
cmake ../source -DCMAKE_TOOLCHAIN_FILE=[VCPKG_DIR]/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 15 2017 Win64"
+
cmake %VCMI_DIR%/source -DCMAKE_TOOLCHAIN_FILE=%VCMI_DIR%/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Visual Studio 16 2019" -A x64
 
</pre>
 
</pre>
+
 
 
== Compile VCMI with Visual Studio ==
 
== Compile VCMI with Visual Studio ==
* open '''[VCMI_DIR]/build/VCMI.sln''' in Visual Studio
+
# open '''%VCMI_DIR%/build/VCMI.sln''' in Visual Studio
* select "Release" build type in combobox
+
# select "Release" build type in combobox
* right click on '''BUILD_ALL''' project - build project
+
# right click on '''BUILD_ALL''' project - build project. This BUILD_ALL project should be in "CMakePredefinedTargets" tree in Solution Explorer.
* right click on '''INSTALL''' project - build project
+
# grab VCMI in '''%VCMI_DIR%/build/bin''' folder!
* grab VCMI in '''[VCMI_DIR]/install''' folder!
+
 
 
 
== Compile VCMI from command line ==
 
== Compile VCMI from command line ==
From '''[VCMI_DIR]/build''' execute followding commands.
 
  
```For release build```
+
'''For release build'''
 
<pre>
 
<pre>
cmake --build . --config Release
+
cmake --build %VCMI_DIR%/build --config Release
 
</pre>
 
</pre>
Will be used by default even "--config" if not specified.
 
  
```For debug build```
+
'''For debug build'''
 
<pre>
 
<pre>
cmake --build . --config Debug
+
cmake --build %VCMI_DIR%/build --config Debug
 
</pre>
 
</pre>
 +
Debug will be used by default even "--config" if not specified.
  
= Create VCMI installer =
+
= Create VCMI installer (This step is not required for just building & development) =
Make sure NSIS is installed to default directory so CMake can find it.
+
Make sure NSIS is installed to default directory or have registry entry so CMake can find it.
  
After you build VCMI execute following command from [VCMI_DIR]/build.  
+
After you build VCMI execute following commands from '''%VCMI_DIR%/build'''.
=== Execute following if you build for Release: ===
+
=== Execute following if you built for Release: ===
 
<pre>
 
<pre>
 
cpack
 
cpack
 
</pre>
 
</pre>
=== If you want debug build: ===
+
=== If you built for Debug: ===
 
<pre>
 
<pre>
 
cpack -C Debug
 
cpack -C Debug
 
</pre>
 
</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.
 +
 +
=== VCMI won't run since some library is missing ===
 +
 +
'''If you open solution using vcmi.sln'''
 +
Try to build INSTALL target and see if its output works as expected. Copy missing libraries or even all libraries from there to your build directory. Or run cpack and use produced installer and see if you can get libs from there. cpack -V will give more info. If cpack complains that it can not find dumpbin try Visual Studio Command Prompt (special version of cmd provided with Visual Studio with additional PATH) or modify PATH to have this tool available. Another alternative if you use prebuilt vcpkg package is to download latest msvc build, install it and copy missing/all libraries from there.
 +
 +
=== 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 means no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary. Instead use RelWithDebInfo configuration. Also Debug configuration might have some compilation issues because it is not checked via CI for now.
 +
 +
=== I got crash within library XYZ.dll ===
 +
 +
VCPKG generated projects quite often have both debug and regular libs available to linker so it can select wrong lib. For stable RelWithDebInfo build you may try to remove debug folder from VCPKG/installed/x64-windows. Same is done on CI. Also it reduces package size at least twice.
 +
 +
=== Some outdated problems ===
 +
 +
All problems of such kind should be solved with proper cmake INSTALL code.
 +
 +
'''Build is successful but can not start new game'''
 +
 +
Check that all non-VCMI dlls in AI and Scripting (vcmilua.dll and vcmierm.dll) folders are also copied to the parent folder so that they are available for vcmi_clent.exe. These are tbb.dll fuzzylite.dll lua51.dll. Also there should be as well folder scripts (lua scripts for ERM). If scripting folder is absent please build vcmiLua and vcmiErm projects. There is no direct dependency between them and vcmi_client for now (2021-08-28)

Latest revision as of 14:53, 10 January 2023

Prerequisites

  • Windows Vista or newer.
  • Microsoft Visual Studio 2017 or 2019
  • CI use VS2019, so you are going to have less problems with it.
  • 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 %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 GitHub Actions.

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 no debug, 3 times smaller file size
  • vcpkg-export-x64-windows-v140.7z to build for 64-bit no debug, 3 times smaller file size
  • vcpkg-export-x86-windows-v140-debug.7z to build for 32-bit with debug configuration available
  • vcpkg-export-x64-windows-v140-debug.7z to build for 64-bit with debug configuration available

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

Please be aware that if you're running 32-bit Windows version, then this is impossible due to https://github.com/microsoft/vcpkg/issues/26036

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 tbb:x64-windows fuzzylite:x64-windows sdl2:x64-windows sdl2-image:x64-windows sdl2-ttf:x64-windows sdl2-mixer[mpg123]:x64-windows boost:x64-windows qt5-base:x64-windows ffmpeg:x64-windows luajit:x64-windows
  • For 64-bit build run
%VCMI_DIR%/vcpkg/vcpkg.exe install install tbb:x86-windows fuzzylite:x86-windows sdl2:x86-windows sdl2-image:x86-windows sdl2-ttf:x86-windows sdl2-mixer[mpg123]:x86-windows boost:x86-windows qt5-base:x86-windows ffmpeg:x86-windows luajit:x86-windows

For the list of the packages used you can also consult vcmi-deps-windows readme in case this article gets outdated a bit.

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 (This step is not required for just building & development)

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.

VCMI won't run since some library is missing

If you open solution using vcmi.sln Try to build INSTALL target and see if its output works as expected. Copy missing libraries or even all libraries from there to your build directory. Or run cpack and use produced installer and see if you can get libs from there. cpack -V will give more info. If cpack complains that it can not find dumpbin try Visual Studio Command Prompt (special version of cmd provided with Visual Studio with additional PATH) or modify PATH to have this tool available. Another alternative if you use prebuilt vcpkg package is to download latest msvc build, install it and copy missing/all libraries from there.

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 means no optimizations at all. Debug information that available for release builds is often sufficient so just avoid full debug builds unless absolutely necessary. Instead use RelWithDebInfo configuration. Also Debug configuration might have some compilation issues because it is not checked via CI for now.

I got crash within library XYZ.dll

VCPKG generated projects quite often have both debug and regular libs available to linker so it can select wrong lib. For stable RelWithDebInfo build you may try to remove debug folder from VCPKG/installed/x64-windows. Same is done on CI. Also it reduces package size at least twice.

Some outdated problems

All problems of such kind should be solved with proper cmake INSTALL code.

Build is successful but can not start new game

Check that all non-VCMI dlls in AI and Scripting (vcmilua.dll and vcmierm.dll) folders are also copied to the parent folder so that they are available for vcmi_clent.exe. These are tbb.dll fuzzylite.dll lua51.dll. Also there should be as well folder scripts (lua scripts for ERM). If scripting folder is absent please build vcmiLua and vcmiErm projects. There is no direct dependency between them and vcmi_client for now (2021-08-28)