Platform-specific guides » macOS

Tips and tricks for macOS.

With Apple decision to focus on Metal, macOS OpenGL support is stuck on version 4.2 (i.e., a version before compute shaders are available). Moreover, OpenGL is deprecated since macOS 10.14.

See also iOS.

Bundle creation

While graphical applications can run "as is", directly from the compiled executable, it's not possible to set various crucial properties of the app such as HiDPI support — for that you need to create a bundle, specifying its options through a *.plist file. If you use CMake, it provides a builtin file with a few options and you can use it like this:

add_executable(my-application main.cpp)
# ...
if(CORRADE_TARGET_APPLE)
    set_target_properties(my-application PROPERTIES
        MACOSX_BUNDLE ON
        MACOSX_BUNDLE_BUNDLE_NAME "My Application"
        MACOSX_BUNDLE_BUNDLE_IDENTIFIER "cz.mosra.magnum.my-application")
endif()

The builtin file doesn't include all possible properties, however it's possible to supply your own. A minimal file can look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleDevelopmentRegion</key>
  <string>en-US</string>
  <key>CFBundleExecutable</key>
  <string>${MACOSX_BUNDLE_EXECUTABLE_NAME}</string>
  <key>CFBundleIdentifier</key>
  <string>{{ package }}</string>
  <key>CFBundleInfoDictionaryVersion</key>
  <string>6.0</string>
  <key>CFBundleName</key>
  <string>{{ app_name }}</string>
  <key>CFBundlePackageType</key>
  <string>APPL</string>
</dict>
</plist>

Replace {{ package }} with Java-like package name for your app (in this case it could be e.g. "cz.mosra.magnum.my_application", for example), {{ app_name }} with human-readable app name that's displayed in the system (so e.g. "My Application"). If you name it MacOSXBundleInfo.plist.in, it can be supplied to the bundle like below. The ${MACOSX_BUNDLE_EXECUTABLE_NAME} will get automatically replaced with the target executable name.

if(CORRADE_TARGET_APPLE)
    set_target_properties(my-application PROPERTIES
        MACOSX_BUNDLE ON
        MACOSX_BUNDLE_INFO_PLIST ${CMAKE_CURRENT_SOURCE_DIR}/MacOSXBundleInfo.plist.in)
endif()

See the official Apple Property List file documentation for information about all options.

If you don't use CMake, these options can be set directly through Xcode UI, for example.

HiDPI (Retina) support

macOS and iOS is the only platform where HiDPI support of an app can't be advertised programmatically. In case of CMake, you have to supply a custom *.plist file with NSHighResolutionCapable enabled (see above for details about creating bundles):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  ...
  <key>NSHighResolutionCapable</key>
  <true/>
</dict>
</plist>

Best practices

Official Apple documentation:

Setting up macOS build on Travis CI

A lot of Travis features is shared between Linux and macOS, see Setting up Linux build on Travis CI for more information.

In general, a macOS build is done by adding the following to your .travis.yml matrix build. See the official documentation for more information.

matrix:
  include:
  - language: cpp
    os: osx
    compiler: clang

Most of the build setup can be shared with Linux, as both systems have roughly the same set of packages. For installing dependencies there's no builtin way, but you can use Homebrew. Be aware that calling for example brew install ninja by default causes Homebrew to update itself first. That currently (March 2018) takes almost two minutes. It's possible to skip the update by setting an environment variable as shown below, however this might fail in case you need a very recent version of a package.

HOMEBREW_NO_AUTO_UPDATE=1 brew install ninja

Troubleshooting