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

@@ -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)

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.

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.

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

modules/FindMagnum.cmake

@@ -52,6 +52,8 @@
 # / MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS to simplify porting.
 #
 # Features of found Magnum library are exposed in these variables:
+#  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
@@ -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)

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
 

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