overte-JulianGro/BUILD_OSX.md

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

  1. Problem: Running the scheme interface.app from Xcode causes a crash for Interface related to libgl.
    1. Cause: The target gl generates a binary called libgl. A macOS libGL.framework item gets loaded instead by Xcode.
    2. Solution: In the Xcode target settings for libgl, set the version to 1.0.0.
  2. Problem: CMake complains about Python 3 being missing.
    1. Cause: CMake might be out of date.
    2. 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.