From a67f0a4ac72f3b8c8b687df47a43b567e2e4db3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nguy=E1=BB=85n=20Gia=20Phong?= Date: Sat, 29 Feb 2020 11:54:49 +0700 Subject: FindOpenAL: Move user-relevant comments into public documentation In particular, the role of frameworks in the search order can help users trying to use the ``OPENALDIR`` environment variable. Fixes: #20334 --- Modules/FindOpenAL.cmake | 69 ++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 35 deletions(-) diff --git a/Modules/FindOpenAL.cmake b/Modules/FindOpenAL.cmake index d3acfc5..c9c0903 100644 --- a/Modules/FindOpenAL.cmake +++ b/Modules/FindOpenAL.cmake @@ -5,27 +5,45 @@ FindOpenAL ---------- - Finds Open Audio Library (OpenAL). -This module defines ``OPENAL_LIBRARY OPENAL_FOUND``, if -false, do not try to link to OpenAL ``OPENAL_INCLUDE_DIR``, where to find -the headers. -``$OPENALDIR`` is an environment variable that would correspond to the -``./configure --prefix=$OPENALDIR`` used in building OpenAL. +Projects using this module should use ``#include `` to include the OpenAL +header file, **not** ``#include ``. The reason for this is that the +latter is not entirely portable. Windows/Creative Labs does not by default put +their headers in ``AL/`` and macOS uses the convention ````. + +Hints +^^^^^ + +Environment variable ``$OPENALDIR`` can be used to set the prefix of OpenAL +installation to be found. + +By default on macOS, system framework is search first. In other words, +OpenAL is searched in the following order: + +1. System framework: ``/System/Library/Frameworks``, whose priority can be + changed via setting the :variable:`CMAKE_FIND_FRAMEWORK` variable. +2. Environment variable ``$OPENALDIR``. +3. System paths. +4. User-compiled framework: ``~/Library/Frameworks``. +5. Manually compiled framework: ``/Library/Frameworks``. +6. Add-on package: ``/opt``. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: -Created by Eric Wing. This was influenced by the ``FindSDL.cmake`` -module. +``OPENAL_FOUND`` + If false, do not try to link to OpenAL +``OPENAL_INCLUDE_DIR`` + OpenAL include directory +``OPENAL_LIBRARY`` + Path to the OpenAL library +``OPENAL_VERSION_STRING`` + Human-readable string containing the version of OpenAL #]=======================================================================] -# This makes the presumption that you are include al.h like -# #include "al.h" -# and not -# #include -# The reason for this is that the latter is not entirely portable. -# Windows/Creative Labs does not by default put their headers in AL/ and -# OS X uses the convention . -# # For Windows, Creative Labs seems to have added a registry key for their # OpenAL 1.1 installer. I have added that key to the list of search paths, # however, the key looks like it could be a little fragile depending on @@ -36,25 +54,6 @@ module. # platforms are introduced. # The OpenAL 1.0 installer doesn't seem to have a useful key I can use. # I do not know if the Nvidia OpenAL SDK has a registry key. -# -# For OS X, remember that OpenAL was added by Apple in 10.4 (Tiger). -# To support the framework, I originally wrote special framework detection -# code in this module which I have now removed with CMake's introduction -# of native support for frameworks. -# In addition, OpenAL is open source, and it is possible to compile on Panther. -# Furthermore, due to bugs in the initial OpenAL release, and the -# transition to OpenAL 1.1, it is common to need to override the built-in -# framework. -# Per my request, CMake should search for frameworks first in -# the following order: -# ~/Library/Frameworks/OpenAL.framework/Headers -# /Library/Frameworks/OpenAL.framework/Headers -# /System/Library/Frameworks/OpenAL.framework/Headers -# -# On OS X, this will prefer the Framework version (if found) over others. -# People will have to manually change the cache values of -# OPENAL_LIBRARY to override this selection or set the CMake environment -# CMAKE_INCLUDE_PATH to modify the search paths. find_path(OPENAL_INCLUDE_DIR al.h HINTS -- cgit v0.12