3.7 KiB
Build macOS
Last Updated on August 12, 2025
Please read the general build guide for information on dependencies required for all platforms. This will include the necessary environment variables to customize your build. Only macOS specific instructions are found in this document.
Prerequisites
CMake, OpenSSL, NPM and Conan
Homebrew is an excellent package manager for macOS. It makes the installation of some Overte dependencies very simple.
brew install cmake npm conan
Note: You can also download alternative CMake versions from Github if needed.
Qt5
While Conan can build Qt from source, we use the Homebrew package instead:
brew install qt@5
Prepare conan
The next step is setting up conan
First, create a conan profile
conan profile detect --force
Next, add the overte remote to conan
conan remote add overte https://artifactory.overte.org/artifactory/api/conan/overte -f
Add CMake 4.0 is currently too new for us, so we tell Conan to get and use an older version.
Add the following to the default Conan profile (which is usually found in ~/.conan2/profiles/default
):
[tool_requires]
!cmake/*: cmake/[>=3 <4]
Compiling
If you installed Qt5 as instructed above, we need to add its path to the environment as instructed by Homebrew:
export PATH="/opt/homebrew/opt/qt@5/bin:$PATH"
If you only need Qt5 on your machine (for example if you only develop Overte), you can make this change permanent as well:
echo 'export PATH="/opt/homebrew/opt/qt@5/bin:$PATH"' >> ~/.zshrc
Install the dependencies with conan
cd overte
conan install . -s build_type=Release -b missing -pr:b=default -of build
Generate and Build
You can choose to use either Unix Makefiles or Xcode.
make
Run CMake.
Prepare makefiles:
cmake --preset conan-release
Build:
cmake --build --preset conan-release
Keep in mind that the interface
target is called overte
on macOS.
To package the installation, you can simply run cmake --build --preset conan-release --target package
afterwards.
Xcode
You can ask CMake to generate Xcode project files instead of Unix Makefiles using the -G Xcode
parameter after CMake.
You will need to select the Xcode installation in the terminal first if you have not done so already.
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
cmake --preset conan-release -G Xcode
After running CMake, you will have the Xcode project file necessary to build all of the components.
Open the overte.xcodeproj
file, choose ALL_BUILD
from the Product > Scheme menu (or target drop down), and click Run.
If the build completes successfully, you will have built targets for all components located in the build/${target_name}/Debug
directories.
FAQ
- Problem: Running the scheme
interface.app
from Xcode causes a crash for Interface related tolibgl
.- Cause: The target
gl
generates a binary calledlibgl
. A macOSlibGL.framework
item gets loaded instead by Xcode. - Solution: In the Xcode target settings for
libgl
, set the version to1.0.0
.
- Cause: The target
- Problem: CMake complains about Python 3 being missing.
- Cause: CMake might be out of date.
- Solution: Try updating your CMake binary with command
brew upgrade cmake
, or by downloading and running a newer CMake installer, depending on how you originally installed CMake. Please keep in mind the recommended CMake versions noted above.