From a6831da902fdf88e068990cc8a448a96cb2ed96a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 24 Oct 2013 16:57:09 +0200 Subject: [PATCH] Initial support for ability to disable building of deprecated APIs. CMake option `BUILD_DEPRECATED`, enabled by default, exposed as `MAGNUM_BUILD_DEPRECATED` to users both in CMake and C++ code. --- CMakeLists.txt | 5 +++++ Doxyfile | 2 +- doc/building.dox | 6 ++++++ doc/cmake.dox | 2 ++ modules/FindMagnum.cmake | 16 +++++++++++----- src/Magnum.h | 11 +++++++++++ src/magnumConfigure.h.cmake | 1 + 7 files changed, 37 insertions(+), 6 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index c1ebcd244..183b8b804 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -63,6 +63,11 @@ else() option(WITH_SDL2APPLICATION "Build Sdl2Application library" OFF) endif() +option(BUILD_DEPRECATED "Include deprecated API in the build" ON) +if(BUILD_DEPRECATED) + set(MAGNUM_BUILD_DEPRECATED 1) +endif() + option(BUILD_STATIC "Build static libraries (default are shared)" OFF) cmake_dependent_option(BUILD_STATIC_PIC "Build static libraries with position-independent code" OFF "BUILD_STATIC" OFF) option(BUILD_TESTS "Build unit tests." OFF) diff --git a/Doxyfile b/Doxyfile index 82e41c360..ee684d052 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1645,7 +1645,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = DOXYGEN_GENERATING_OUTPUT +PREDEFINED = DOXYGEN_GENERATING_OUTPUT MAGNUM_BUILD_DEPRECATED # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/doc/building.dox b/doc/building.dox index c7993bde8..b5f463926 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -121,6 +121,12 @@ Clang), pass `-DCMAKE_CXX_COMPILER=clang++` to CMake. the module with your code instead of depending on it being in system location. You can install it by enabling `WITH_FIND_MODULE`. +The library is constantly evolving and thus some APIs are deprecated and then +later removed in favor of better ones. To preserve backwards compatibility, +%Magnum is by default built with all deprecated APIs. However, to make your +code more robust and future-proof, it's recommended to build the library with +`BUILD_DEPRECATED` disabled. + By default the engine is built for desktop OpenGL. Using `TARGET_*` CMake parameters you can target other platforms. Note that some features are available for desktop OpenGL only, see @ref requires-gl. diff --git a/doc/cmake.dox b/doc/cmake.dox index 6493356b5..cfaca8c6c 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -96,6 +96,8 @@ convenience aliases `MAGNUM_APPLICATION_LIBRARIES` / Features of found %Magnum library are exposed in these CMake variables, they are also available as preprocessor variables if including Magnum.h: +- `MAGNUM_BUILD_DEPRECATED` -- Defined if compiled with deprecated APIs + included - `MAGNUM_BUILD_STATIC` -- Defined if built as static libraries. Default are shared libraries. - `MAGNUM_TARGET_GLES` -- Defined if compiled for OpenGL ES diff --git a/modules/FindMagnum.cmake b/modules/FindMagnum.cmake index fd0e5467e..b63d1cb7f 100644 --- a/modules/FindMagnum.cmake +++ b/modules/FindMagnum.cmake @@ -52,11 +52,13 @@ # / MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS to simplify porting. # # Features of found Magnum library are exposed in these variables: -# MAGNUM_BUILD_STATIC - Defined if compiled as static libraries -# MAGNUM_TARGET_GLES - Defined if compiled for OpenGL ES -# MAGNUM_TARGET_GLES2 - Defined if compiled for OpenGL ES 2.0 -# MAGNUM_TARGET_GLES3 - Defined if compiled for OpenGL ES 3.0 -# MAGNUM_TARGET_DESKTOP_GLES - Defined if compiled with OpenGL ES +# MAGNUM_BUILD_DEPRECATED - Defined if compiled with deprecated APIs +# included +# MAGNUM_BUILD_STATIC - Defined if compiled as static libraries +# MAGNUM_TARGET_GLES - Defined if compiled for OpenGL ES +# MAGNUM_TARGET_GLES2 - Defined if compiled for OpenGL ES 2.0 +# MAGNUM_TARGET_GLES3 - Defined if compiled for OpenGL ES 3.0 +# MAGNUM_TARGET_DESKTOP_GLES - Defined if compiled with OpenGL ES # emulation on desktop OpenGL # # Additionally these variables are defined for internal usage: @@ -123,6 +125,10 @@ find_path(MAGNUM_INCLUDE_DIR # Configuration file(READ ${MAGNUM_INCLUDE_DIR}/magnumConfigure.h _magnumConfigure) +string(FIND "${_magnumConfigure}" "#define MAGNUM_BUILD_DEPRECATED" _BUILD_DEPRECATED) +if(NOT _BUILD_DEPRECATED EQUAL -1) + set(MAGNUM_BUILD_DEPRECATED 1) +endif() string(FIND "${_magnumConfigure}" "#define MAGNUM_BUILD_STATIC" _BUILD_STATIC) if(NOT _BUILD_STATIC EQUAL -1) set(MAGNUM_BUILD_STATIC 1) diff --git a/src/Magnum.h b/src/Magnum.h index 4d8527e1b..c38936b9c 100644 --- a/src/Magnum.h +++ b/src/Magnum.h @@ -65,6 +65,17 @@ using Corrade::Utility::Warning; using Corrade::Utility::Error; #ifdef DOXYGEN_GENERATING_OUTPUT +/** +@brief Build with deprecated API included + +Defined if the library contains deprecated API (which will be removed in the +future). To preserve backward compatibility, %Magnum is by default built with +deprecated API included. +@see @ref building +*/ +#define MAGNUM_BUILD_DEPRECATED +/* (enabled by default) */ + /** @brief Static library build diff --git a/src/magnumConfigure.h.cmake b/src/magnumConfigure.h.cmake index 1cb5f49b5..e6b255e1c 100644 --- a/src/magnumConfigure.h.cmake +++ b/src/magnumConfigure.h.cmake @@ -22,6 +22,7 @@ DEALINGS IN THE SOFTWARE. */ +#cmakedefine MAGNUM_BUILD_DEPRECATED #cmakedefine MAGNUM_BUILD_STATIC #cmakedefine MAGNUM_TARGET_GLES #cmakedefine MAGNUM_TARGET_GLES2