|
|
| (6 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| − | = Requirements =
| + | {{Template:MovedToWebpage|https://vcmi.eu/developers/Building_macOS/}} |
| − | # C++ toolchain, either of:
| |
| − | #* Xcode Command Line Tools: <code>sudo xcode-select --install</code>
| |
| − | #* Xcode IDE: https://developer.apple.com/xcode/
| |
| − | #* (not tested) other C++ compilers, e.g. gcc/clang from [https://brew.sh/ Homebrew]
| |
| − | # CMake: <code>brew install --cask cmake</code> or get from https://cmake.org/download/
| |
| − | # (optional) Ninja: <code>brew install ninja</code> or get from https://github.com/ninja-build/ninja/releases
| |
| − | | |
| − | = Obtaining source code =
| |
| − | Clone https://github.com/vcmi/vcmi with submodules. Example for command line:
| |
| − | <nowiki>git clone --recurse-submodules https://github.com/vcmi/vcmi.git</nowiki>
| |
| − | | |
| − | = Obtaining dependencies =
| |
| − | There're 2 ways to get dependencies automatically.
| |
| − | | |
| − | == Conan package manager ==
| |
| − | That's what our CI uses.
| |
| − | | |
| − | # [https://docs.conan.io/en/latest/installation.html Install Conan]
| |
| − | # Execute in Terminal: <code>conan profile new default --detect</code>
| |
| − | # Download prebuilt libraries from [https://github.com/vcmi/vcmi-deps-macos/releases GitHub Releases]:
| |
| − | #* if you're on an Intel Mac, download file '''intel.txz''' and unpack it to <code>~/.conan</code> directory.
| |
| − | #* if you're on an ARM Mac, download file '''intel-cross-arm.txz''' and unpack it to <code>~/.conan</code> directory. Then follow [https://github.com/vcmi/vcmi-ios-deps#note-for-arm-macs instructions how to build Qt host tools for ARM], on step 3 copy them to <code>~/.conan/data/qt/5.15.5/_/_/package/SOME_HASH/bin</code>.
| |
| − | # In Terminal <code>cd</code> to the source code directory and run:
| |
| − | <blockquote>USE_CONAN_WITH_ALL_CONFIGS=1 conan install . --install-folder='''conan-generated''' --no-imports --build=never --profile:build=default --profile:host=CI/conan/'''PROFILE'''</blockquote>
| |
| − | where '''conan-generated''' can be any directory you like (Conan helper files will appear there) and '''PROFILE''' must be replaced with:
| |
| − | * if you're on an Intel Mac: <code>macos-intel</code>
| |
| − | * if you're on an ARM Mac: <code>macos-arm</code>
| |
| − | | |
| − | == Homebrew ==
| |
| − | # [https://brew.sh/ Install Homebrew]
| |
| − | # Install dependencies: <code>brew install boost ffmpeg@4 luajit minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb</code>
| |
| − | # Install Qt dependency in either of the ways (note that you can skip this if you're not going to build Launcher):
| |
| − | #* <code>brew install qt@5</code> for Qt 5 or <code>brew install qt</code> for Qt 6
| |
| − | #* using [https://www.qt.io/download Qt Online Installer] - choose '''Go open source'''
| |
| − | | |
| − | = Preparing build environment =
| |
| − | This applies only to Xcode-based toolchain. If <code>xcrun -f clang</code> prints errors, then use either of the following ways:
| |
| − | * select an Xcode instance from Xcode application - Preferences - Locations - Command Line Tools
| |
| − | * use <code>xcode-select</code> utility to set Xcode or Xcode Command Line Tools path: for example, <code>sudo xcode-select -s /Library/Developer/CommandLineTools</code>
| |
| − | * set <code>DEVELOPER_DIR</code> environment variable pointing to Xcode or Xcode Command Line Tools path: for example, <code>export DEVELOPER_DIR=/Applications/Xcode.app</code>
| |
| − | | |
| − | = Configuring project for building =
| |
| − | Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE.
| |
| − | | |
| − | # In Terminal <code>cd</code> to the source code directory
| |
| − | # Start assembling CMake invocation: type <code>cmake -S . -B BUILD_DIR</code> where ''BUILD_DIR'' can be any path, don't press Return
| |
| − | # Decide which CMake generator you want to use:
| |
| − | #* Makefiles: no extra option needed or pass <code>-G 'Unix Makefiles'</code>
| |
| − | #* Ninja (if you have installed it): pass <code>-G Ninja</code>
| |
| − | #* Xcode IDE (if you have installed it): pass <code>-G Xcode</code>
| |
| − | # If you picked Makefiles or Ninja, pick desired ''build type'' - either of Debug / RelWithDebInfo / Release / MinSizeRel - and pass it in <code>CMAKE_BUILD_TYPE</code> option, for example: <code>-D CMAKE_BUILD_TYPE=Release</code>. If you don't pass this option, <code>RelWithDebInfo</code> will be used.
| |
| − | # If you don't want to run tests, pass <code>-D ENABLE_TEST=OFF</code>
| |
| − | # If you don't want to build Launcher, pass <code>-D ENABLE_LAUNCHER=OFF</code>
| |
| − | # You can also pass <code>-Wno-dev</code> if you're not interested in CMake developer warnings
| |
| − | # Next step depends on the dependency manager you have picked:
| |
| − | #* Conan: pass <code>-D CMAKE_TOOLCHAIN_FILE=conan-generated/conan_toolchain.cmake</code> where '''conan-generated''' must be replaced with your name choice at step 4 of [[#Conan package manager]]
| |
| − | #* Homebrew: pass <code>-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4)"</code>
| |
| − | #** if you installed Qt 5 from Homebrew, '''append''' to the above option but '''before the closing quote''': <code>;$(brew --prefix qt@5)</code>
| |
| − | #** if you installed Qt from Online Installer, '''append''' to the above option but '''before the closing quote''' your path to Qt directory, for example: <code>;/Users/kambala/dev/Qt-libs/5.15.2/Clang64</code>
| |
| − | #** example of what you should pass in the first case: <code>-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4);$(brew --prefix qt@5)"</code>
| |
| − | # If you're on an ARM Mac and using Conan, also pass: <code>-D ENABLE_ERM=OFF -D ENABLE_LUA=OFF</code>
| |
| − | # now press Return
| |
| − | | |
| − | = Building project =
| |
| − | | |
| − | You must also install game files to be able to run the built version, see [[Installation on macOS]].
| |
| − | | |
| − | == From Xcode IDE ==
| |
| − | Open <code>VCMI.xcodeproj</code> from the build directory, select <code>vcmiclient</code> scheme and hit Run (Cmd+R). To build Launcher, select <code>vcmilauncher</code> scheme instead.
| |
| − | | |
| − | == From command line ==
| |
| − | <code>cmake --build <path to build directory> --target vcmiclient</code>
| |
| − | | |
| − | * If using Makefiles generator, you'd want to utilize all your CPU cores by appending <code>-- -j$(sysctl -n hw.ncpu)</code> to the above
| |
| − | * If using Xcode generator, you can also choose which configuration to build by appending <code>--config <configuration name></code> to the above, for example: <code>--config Debug</code>
| |
| − | | |
| − | = Packaging project into DMG file =
| |
| − | After building, run <code>cpack</code> from the build directory. If using Xcode generator, also pass <code>-C <configuration name></code> with the same configuration that you used to build the project.
| |
| − | | |
| − | = 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>
| |
| − | BUILD_DIR/bin/vcmilauncher
| |
| − | BUILD_DIR/bin/vcmiclient
| |
| − | BUILD_DIR/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.
| |
| − | | |
| − | = 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-1.0.dmg
| |
| − | # Detach volume:
| |
| − | hdiutil detach /Volumes/vcmi-1.0
| |
| − | # To view dependency paths
| |
| − | otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient
| |
| − | # To display load commands such as LC_RPATH
| |
| − | otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient
| |
| − | </pre>
| |
| − | | |
| − | = Troubleshooting =
| |
| − | In case of troubles you can always consult our CI build scripts or contact the dev team via slack
| |
