1
0
mirror of https://github.com/vcmi/vcmi.git synced 2024-12-14 10:12:59 +02:00
vcmi/docs/developers/Building_macOS.md

120 lines
6.3 KiB
Markdown
Raw Normal View History

## Requirements
2023-09-01 14:25:21 +02:00
2023-09-27 14:25:41 +02:00
1. C++ toolchain, either of:
- Xcode Command Line Tools (aka CLT): `sudo xcode-select --install`
- Xcode IDE: <https://developer.apple.com/xcode/>
- (not tested) other C++ compilers, e.g. gcc/clang from [Homebrew](https://brew.sh/)
2. CMake: `brew install --cask cmake` or get from <https://cmake.org/download/>
2023-10-08 21:18:44 +02:00
4. Optional:
* Ninja: `brew install ninja` or get it from <https://github.com/ninja-build/ninja/releases>
2023-10-08 21:47:09 +02:00
* CCache to speed up recompilation: `brew install ccache`
2023-09-01 14:25:21 +02:00
## Obtaining source code
2023-09-01 14:25:21 +02:00
Clone <https://github.com/vcmi/vcmi> with submodules. Example for command line:
2023-09-27 14:25:41 +02:00
```
git clone --recurse-submodules https://github.com/vcmi/vcmi.git
```
2023-09-01 14:25:21 +02:00
## Obtaining dependencies
2023-09-01 14:25:21 +02:00
There're 2 ways to get dependencies automatically.
### Conan package manager
2023-09-01 14:25:21 +02:00
Please find detailed instructions [here](./Conan.md). Note that the link points to the state of the current branch, for the latest release check the same document in the [master branch](https://github.com/vcmi/vcmi/blob/master/docs/developers/Сonan.md).
2023-09-01 14:25:21 +02:00
On the step where you need to replace **PROFILE**, choose:
2023-09-27 14:25:41 +02:00
- if you're on an Intel Mac: `macos-intel`
- if you're on an Apple Silicon Mac: `macos-arm`
2023-09-01 14:25:21 +02:00
Note: if you wish to build 1.0 release in non-`Release` configuration, you should define `USE_CONAN_WITH_ALL_CONFIGS=1` environment variable when executing `conan install`.
### Homebrew
2023-09-01 14:25:21 +02:00
2023-09-27 14:25:41 +02:00
1. [Install Homebrew](https://brew.sh/)
2. Install dependencies: `brew install boost minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb`
3. If you want to watch in-game videos, also install FFmpeg: `brew install ffmpeg@4`
4. Install Qt dependency in either of the ways (note that you can skip this if you're not going to build Launcher):
- `brew install qt@5` for Qt 5 or `brew install qt` for Qt 6
- using [Qt Online Installer](https://www.qt.io/download) - choose **Go open source**
2023-09-01 14:25:21 +02:00
## Preparing build environment
2023-09-01 14:25:21 +02:00
This applies only to Xcode-based toolchain. If `xcrun -f clang` prints errors, then use either of the following ways:
2023-09-27 14:25:41 +02:00
- select an Xcode instance from Xcode application - Preferences - Locations - Command Line Tools
- use `xcode-select` utility to set Xcode or Xcode Command Line Tools path: for example, `sudo xcode-select -s /Library/Developer/CommandLineTools`
- set `DEVELOPER_DIR` environment variable pointing to Xcode or Xcode Command Line Tools path: for example, `export DEVELOPER_DIR=/Applications/Xcode.app`
2023-09-01 14:25:21 +02:00
## Configuring project for building
2023-09-01 14:25:21 +02:00
Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE.
2023-09-27 14:25:41 +02:00
1. In Terminal `cd` to the source code directory
2. Start assembling CMake invocation: type `cmake -S . -B BUILD_DIR` where *BUILD_DIR* can be any path, **don't press Return**
3. Decide which CMake generator you want to use:
- Makefiles: no extra option needed or pass `-G 'Unix Makefiles'`
- Ninja (if you have installed it): pass `-G Ninja`
- Xcode IDE (if you have installed it): pass `-G Xcode`
4. If you picked Makefiles or Ninja, pick desired *build type* - either of Debug / RelWithDebInfo / Release / MinSizeRel - and pass it in `CMAKE_BUILD_TYPE` option, for example: `-D CMAKE_BUILD_TYPE=Release`. If you don't pass this option, `RelWithDebInfo` will be used.
5. If you don't want to build Launcher, pass `-D ENABLE_LAUNCHER=OFF`
6. You can also pass `-Wno-dev` if you're not interested in CMake developer warnings
7. Next step depends on the dependency manager you have picked:
- Conan: pass `-D CMAKE_TOOLCHAIN_FILE=conan-generated/conan_toolchain.cmake` where **conan-generated** must be replaced with your directory choice
- Homebrew: if you installed FFmpeg or Qt 5, you need to pass `-D "CMAKE_PREFIX_PATH="` variable. See below what you can insert after `=` (but **before the closing quote**), multiple values must be separated with `;` (semicolon):
- if you installed FFmpeg, insert `$(brew --prefix ffmpeg@4)`
- if you installed Qt 5 from Homebrew, insert:`$(brew --prefix qt@5)`
- if you installed Qt from Online Installer, insert your path to Qt directory, for example: `/Users/kambala/dev/Qt-libs/5.15.2/Clang64`
- example for FFmpeg + Qt 5: `-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4);$(brew --prefix qt@5)"`
2023-10-08 21:47:09 +02:00
8. If you want to speed up the recompilation, add `-D ENABLE_CCACHE=ON`
9. Now press Return
2023-09-01 14:25:21 +02:00
## Building project
2023-09-01 14:25:21 +02:00
2023-09-04 23:52:36 +02:00
You must also install game files to be able to run the built version, see [Installation on macOS](players/Installation_macOS.md).
2023-09-01 14:25:21 +02:00
### From Xcode IDE
2023-09-01 14:25:21 +02:00
Open `VCMI.xcodeproj` from the build directory, select `vcmiclient` scheme and hit Run (Cmd+R). To build Launcher, select `vcmilauncher` scheme instead.
### From command line
2023-09-01 14:25:21 +02:00
2023-09-27 14:25:41 +02:00
`cmake --build <path to build directory>`
2023-09-01 14:25:21 +02:00
2023-09-27 14:25:41 +02:00
- If using Makefiles generator, you'd want to utilize all your CPU cores by appending `-- -j$(sysctl -n hw.ncpu)` to the above
- If using Xcode generator, you can also choose which configuration to build by appending `--config <configuration name>` to the above, for example: `--config Debug`
2023-09-01 14:25:21 +02:00
## Packaging project into DMG file
2023-09-01 14:25:21 +02:00
After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C `<configuration name> with the same configuration that you used to build the project.
2023-09-04 23:52:36 +02:00
If you use Conan, it's expected that you use **conan-generated** directory at step 4 of [Conan package manager](Conan.md).
2023-09-01 14:25:21 +02:00
## Running VCMI
2023-09-01 14:25:21 +02:00
You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.
2023-09-27 14:25:41 +02:00
Alternatively you can run binaries directly from the **bin** directory:
2023-09-01 14:25:21 +02:00
2023-09-27 14:25:41 +02:00
- BUILD_DIR/bin/vcmilauncher
- BUILD_DIR/bin/vcmiclient
- BUILD_DIR/bin/vcmiserver
2023-09-01 14:25:21 +02:00
2023-09-27 14:25:41 +02:00
CMake include commands to copy all needed assets from source directory into the **bin** directory on each build. They'll work when you build from Xcode too.
2023-09-01 14:25:21 +02:00
## Some useful debugging tips
2023-09-01 14:25:21 +02:00
Anyone who might want to debug builds, but new to macOS could find following commands useful:
2023-09-27 14:25:41 +02:00
- 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`
2023-09-01 14:25:21 +02:00
## Troubleshooting
2023-09-01 14:25:21 +02:00
2024-07-10 12:49:53 +02:00
In case of troubles you can always consult our CI build scripts or contact the dev team via discord.