Difference between revisions of "How to build VCMI (macOS)"

From VCMI Project Wiki
Jump to: navigation, search
(Preparing place)
(29 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Prerequisites ==
+
= Installing dependencies =
* Xcode. Can be downloaded from Mac App Store.
+
===== Installing Xcode =====
* CMake. Can be downloaded from ([http://www.cmake.org/cmake/resources/software.html link]) or installed from Homebrew/MacPorts
+
App Store -> Xcode
* Any git client you prefer.
+
Launch it after the installation to agree with it's license terms.
  
== Preparing place ==
+
Alternatively Xcode can be downloaded from Apple Developers website.
Open terminal and go to directory where you want to place vcmi and run:
+
Registration is easier and every possible version is available: https://developer.apple.com/download/more/
 +
 
 +
===== Setting Xcode version Xcode =====
 +
In case you have some weird CMake errors during generation attempts such as
 +
<pre>
 +
CMake Error: Xcode 1.5 not supported.
 +
</pre>
 +
You might need to specify installed version of Xcode:
 
<pre>
 
<pre>
mkdir vcmi && cd vcmi
+
sudo /usr/bin/xcode-select --switch /Users/admin/Downloads/Xcode.app
git clone https://github.com/vcmi/vcmi.git
 
cd vcmi
 
sh osx/download_dependencies.sh
 
 
</pre>
 
</pre>
* Open vcmibuilder.xcodeproj located at vcmi/osx/osx-vcmibuilder
+
After that Cmake will be able to generate projects properly!
* Archive it (Product -> Archive) and than (in Organizer window press Distribute -> Export as: Application) save it in vcmi/osx directory
+
 
 +
===== Installing [https://brew.sh/ Homebrew] =====
 +
<pre>
 +
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 +
</pre>
 +
 
 +
===== Installing dependencies using Homebrew =====
 +
<pre>
 +
brew install git cmake sdl2 sdl2_ttf sdl2_image boost ffmpeg minizip
 +
brew install sdl2_mixer --with-smpeg2
 +
# Now install Qt5 for launcher
 +
brew install qt5
 +
# Make sure to read brew output on Qt carefully
 +
# It's will tell you how to add Qt to your $PATH environment variable
 +
#
 +
# Currently it's can be done like that
 +
# echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile
 +
</pre>
 +
 
 +
= Building VCMI in command line with Makefiles =
 +
===== Getting and configuring VCMI =====
 +
<pre>
 +
# You can choose any directory
 +
mkdir ~/DEV && cd ~/DEV
 +
# Clone VCMI with all submodules
 +
git clone --recursive  https://github.com/vcmi/vcmi.git
 +
# Creating directory for building
 +
mkdir cmake && cd cmake
 +
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -Wno-devc
 +
</pre>
 +
You can as well build VCMI without Qt5 or launcher by disabling it:
 +
<pre>
 +
# But please don't do that unless you know what you're doing
 +
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DENABLE_LAUNCHER=0 -Wno-devc
 +
</pre>
 +
 
 +
===== Building and packaging VCMI =====
 +
<pre>
 +
cd ~/DEV/cmake
 +
# Start build using cmake
 +
cmake --build . -- -j 4
 +
# Or you can as well use simple
 +
# make -j 4
 +
 
 +
# When build is completed you can trigger packaging into DMG
 +
cpack
 +
# After file named such as "vcmi-0.99.dmg" will be created
 +
</pre>
 +
 
 +
= Building VCMI with Xcode =
 +
===== Getting and configuring VCMI =====
 +
<pre>
 +
# You can choose any directory
 +
mkdir ~/DEV && cd ~/DEV
 +
# Clone VCMI with all submodules
 +
git clone --recursive  https://github.com/vcmi/vcmi.git
 +
# Creating directory for building
 +
mkdir cmake && cd cmake
 +
# Xcode is multi-configuration project so specifying CMAKE_BUILD_TYPE makes no sense
 +
cmake ../vcmi -G "Xcode"
 +
 
 +
# You can as well open project in Xcode using:
 +
open VCMI.xcodeproj
 +
</pre>
 +
 
 +
===== Building and packaging VCMI =====
 +
<pre>
 +
cd ~/DEV/xcode
 +
# Start build. Xcode built using multiple processes by default so you don't need to specify it
 +
# Since it's multi-configuration project you need to specify if you want Debug build since Release is default
 +
cmake --build . --config Debug
 +
 
 +
# You have to specify build configuration for CPack. Otherwise it's will expect Release as default
 +
cpack -C Debug
 +
</pre>
 +
 
 +
= Building VCMI with Qt Creator =
 +
When opening project with Qt Creator installed using online installer you might have a problem with CMake unable to find Qt even if you added it into the $PATH environment variable. In that case try to open it from command line:
 +
<pre>
 +
open ~/Qt/Qt\ Creator.app
 +
</pre>
 +
 
 +
= Running VCMI =
 +
You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.
 +
 
 +
Alternatively you can run binaries directly from "bin" directory:
 +
<pre>
 +
~/DEV/cmake/bin/vcmilauncher
 +
~/DEV/cmake/bin/vcmiclient
 +
~/DEV/cmake/bin/vcmiserver
 +
</pre>
 +
CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.
 +
 
 +
'''Be aware you still need directories "Data", "Mp3" and "Maps" from Heroes 3 game assets in VCMI app data directory:'''
 +
<pre>
 +
~/Library/Application\ Support/vcmi/
 +
</pre>
 +
 
 +
===== Some useful debugging tips =====
 +
Anyone who might want to debug builds, but new to macOS could find following commands useful:
 +
<pre>
 +
# To attach DMG file from command line use
 +
hdiutil attach vcmi-0.99.dmg
 +
# Detach volume:
 +
hdiutil detach /Volumes/vcmi-0.99
 +
# To view dependency paths
 +
otool -L /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient
 +
# To display load commands such as LC_RPATH
 +
otool -l /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient
 +
</pre>
 +
 
 +
= Troubleshooting =
 +
# While building '''FuzzyLite''' you may get the following error with the most recent clang: ([https://forum.vcmi.eu/t/cant-build-on-macos-sierra-10-12-6/4315/2 credit to SXX's answer on the forum])
 +
<syntaxhighlight lang="bash">
 +
/tmp/fuzzylite/fuzzylite/./fl/Operation.h:1044:24: error: passing an object that undergoes default argument promotion to 'va_start' has undefined behavior [-Werror,-Wvarargs]
 +
va_start(args, first);
 +
^
 +
</syntaxhighlight>
 +
 
 +
For the time being, you could bypass it using older version of Xcode like 8.2.1 or adding <code>-Wno-varargs</code> compile option to '''AI/FuzzyLite/fuzzylite/CMakeLists.txt:'''
  
== Building ==
+
<syntaxhighlight lang="cmake">
* Open terminal in vcmi directory:
+
if(NOT MSVC)
<pre>mkdir build && cd build
+
#TODO: Remove -Werror before release.
cmake -G Xcode ..</pre>
+
#Add Unix compilation flags
* Open generated Xcode project vcmi.xcodeproj
+
    set(CMAKE_CXX_FLAGS "-pedantic -Wall -Wextra -Werror -Wno-varargs ${CMAKE_CXX_FLAGS}")
* Select vcmiclient in list of targets and press Run (Command + R)
+
</syntaxhighlight>

Revision as of 15:37, 24 September 2017

Installing dependencies

Installing Xcode

App Store -> Xcode Launch it after the installation to agree with it's license terms.

Alternatively Xcode can be downloaded from Apple Developers website. Registration is easier and every possible version is available: https://developer.apple.com/download/more/

Setting Xcode version Xcode

In case you have some weird CMake errors during generation attempts such as

CMake Error: Xcode 1.5 not supported.

You might need to specify installed version of Xcode:

sudo /usr/bin/xcode-select --switch /Users/admin/Downloads/Xcode.app

After that Cmake will be able to generate projects properly!

Installing Homebrew
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Installing dependencies using Homebrew
brew install git cmake sdl2 sdl2_ttf sdl2_image boost ffmpeg minizip
brew install sdl2_mixer --with-smpeg2
# Now install Qt5 for launcher
brew install qt5
# Make sure to read brew output on Qt carefully
# It's will tell you how to add Qt to your $PATH environment variable
#
# Currently it's can be done like that
# echo 'export PATH="/usr/local/opt/qt/bin:$PATH"' >> ~/.bash_profile

Building VCMI in command line with Makefiles

Getting and configuring VCMI
# You can choose any directory
mkdir ~/DEV && cd ~/DEV
# Clone VCMI with all submodules
git clone --recursive  https://github.com/vcmi/vcmi.git
# Creating directory for building
mkdir cmake && cd cmake
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -Wno-devc

You can as well build VCMI without Qt5 or launcher by disabling it:

# But please don't do that unless you know what you're doing
cmake ../vcmi -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DENABLE_LAUNCHER=0 -Wno-devc
Building and packaging VCMI
cd ~/DEV/cmake
# Start build using cmake
cmake --build . -- -j 4
# Or you can as well use simple
# make -j 4

# When build is completed you can trigger packaging into DMG
cpack
# After file named such as "vcmi-0.99.dmg" will be created

Building VCMI with Xcode

Getting and configuring VCMI
# You can choose any directory
mkdir ~/DEV && cd ~/DEV
# Clone VCMI with all submodules
git clone --recursive  https://github.com/vcmi/vcmi.git
# Creating directory for building
mkdir cmake && cd cmake
# Xcode is multi-configuration project so specifying CMAKE_BUILD_TYPE makes no sense
cmake ../vcmi -G "Xcode"

# You can as well open project in Xcode using:
open VCMI.xcodeproj
Building and packaging VCMI
cd ~/DEV/xcode
# Start build. Xcode built using multiple processes by default so you don't need to specify it
# Since it's multi-configuration project you need to specify if you want Debug build since Release is default
cmake --build . --config Debug

# You have to specify build configuration for CPack. Otherwise it's will expect Release as default
cpack -C Debug

Building VCMI with Qt Creator

When opening project with Qt Creator installed using online installer you might have a problem with CMake unable to find Qt even if you added it into the $PATH environment variable. In that case try to open it from command line:

open ~/Qt/Qt\ Creator.app

Running VCMI

You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.

Alternatively you can run binaries directly from "bin" directory:

~/DEV/cmake/bin/vcmilauncher
~/DEV/cmake/bin/vcmiclient
~/DEV/cmake/bin/vcmiserver

CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.

Be aware you still need directories "Data", "Mp3" and "Maps" from Heroes 3 game assets in VCMI app data directory:

~/Library/Application\ Support/vcmi/
Some useful debugging tips

Anyone who might want to debug builds, but new to macOS could find following commands useful:

# To attach DMG file from command line use
hdiutil attach vcmi-0.99.dmg
# Detach volume:
hdiutil detach /Volumes/vcmi-0.99
# To view dependency paths
otool -L /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient
# To display load commands such as LC_RPATH 
otool -l /Volumes/vcmi-0.99/VCMI.app/Contents/MacOS/vcmiclient

Troubleshooting

  1. While building FuzzyLite you may get the following error with the most recent clang: (credit to SXX's answer on the forum)
/tmp/fuzzylite/fuzzylite/./fl/Operation.h:1044:24: error: passing an object that undergoes default argument promotion to 'va_start' has undefined behavior [-Werror,-Wvarargs]
 va_start(args, first);
 ^

For the time being, you could bypass it using older version of Xcode like 8.2.1 or adding -Wno-varargs compile option to AI/FuzzyLite/fuzzylite/CMakeLists.txt:

if(NOT MSVC)
#TODO: Remove -Werror before release.
#Add Unix compilation flags
    set(CMAKE_CXX_FLAGS "-pedantic -Wall -Wextra -Werror -Wno-varargs ${CMAKE_CXX_FLAGS}")