/* This file is part of Magnum. Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Vladimír Vondruš Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ namespace Magnum { /** @page platforms-macos macOS @brief Tips and tricks for macOS @tableofcontents @m_footernavigation @todoc code coverage 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 @ref platforms-ios. @section platforms-macos-bundle 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 @ref platforms-macos-hidpi "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](https://cmake.org/cmake/help/latest/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.html) with a few options and you can use it like this: @code{.cmake} 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() @endcode The builtin file doesn't include all possible properties, however it's possible to supply your own. A minimal file can look like this: @code{.xml-jinja} CFBundleDevelopmentRegion en-US CFBundleExecutable ${MACOSX_BUNDLE_EXECUTABLE_NAME} CFBundleIdentifier {{ package }} CFBundleInfoDictionaryVersion 6.0 CFBundleName {{ app_name }} CFBundlePackageType APPL @endcode Replace @cb{.jinja} {{ package }} @ce with Java-like package name for your app (in this case it could be e.g. @cpp "cz.mosra.magnum.my_application" @ce, for example), @cb{.jinja} {{ app_name }} @ce with human-readable app name that's displayed in the system (so e.g. @cpp "My Application" @ce). If you name it `MacOSXBundleInfo.plist.in`, it can be supplied to the bundle like below. The @cb{.cmake} ${MACOSX_BUNDLE_EXECUTABLE_NAME} @ce will get automatically replaced with the target executable name. @code{.cmake} 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() @endcode See [the official Apple Property List file documentation](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html) for information about all options. If you don't use CMake, these options can be set directly through Xcode UI, for example. @section platforms-macos-hidpi HiDPI (Retina) support macOS and iOS is the only platform where HiDPI support of an app can't be advertised programmatically. According to various sources, this capability is enabled by default on macOS 10.15+ and iOS 13+, for older versions you need to supply a custom `*.plist` file with `NSHighResolutionCapable` enabled: @code{.xml} ... NSHighResolutionCapable @endcode If you are using CMake, you can use the @ref platforms-macos-bundle "method described above" to create a bundle with given file. Also note that this property is already included in CMake's builtin `Info.plist` on [version 3.9 and newer](https://gitlab.kitware.com/cmake/cmake/merge_requests/682). @section platforms-macos-clang-version-mapping Clang version mapping Apple Clang has a different versioning scheme from upstream Clang, making it hard to know which Clang version corresponds to which Apple Clang version. Wikipedia has a [handy version mapping table](https://en.wikipedia.org/wiki/Xcode#Toolchain_versions). CMake exposes Apple Clang as `AppleClang`, so a complete check for e.g. upstream version 5 needs to look like this: @code{.cmake} if((CMAKE_CXX_COMPILER_ID STREQUAL "Clang" AND NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS "5.0") OR (CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang" AND NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS "9.3")) # Code requiring Clang 5 and newer endif() @endcode @note CMake supports `VERSION_GREATER_EQUAL` in the @cb{.cmake} if() @ce statement only [since version 3.7](https://cmake.org/cmake/help/latest/release/3.7.html#commands), use a negated `VERSION_LESS` like above in older versions. @see @ref platforms-windows-msvc-version-mapping @section platforms-macos-opengl-best-practices Best practices Official Apple documentation: - [Best Practices for Working with Vertex Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_vertexdata/opengl_vertexdata.html) - [Best Practices for Working with Texture Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_texturedata/opengl_texturedata.html) @section platforms-macos-travis Setting up macOS build on Travis CI A lot of Travis features is shared between Linux and macOS, see @ref platforms-linux-travis for more information. In general, a macOS build is done by adding the following to your `.travis.yml` matrix build. See [the official documentation](https://docs.travis-ci.com/user/reference/osx/) for more information. @code{.yml} matrix: include: - language: cpp os: osx compiler: clang @endcode 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 @cb{.sh} brew install ninja @ce 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. @code{.sh} HOMEBREW_NO_AUTO_UPDATE=1 brew install ninja @endcode @section platforms-macos-troubleshooting Troubleshooting - @ref GL::AbstractShaderProgram::validate() expects that the shader has a properly configured framebuffer bound along with proper @ref GL::Renderer setup. That is often hard to achieve, so the function cannot be portably used for shader validity testing. - `GL_TIMESTAMP` used by @ref GL::TimeQuery::timestamp() is not implemented on macOS and gives zero results. */ }