Add FUTURE build option

CMakeLists.txt

@@ -104,6 +104,8 @@ option(INSTALL_PKGCONFIG "Install pkgconfig file" ON)
 option(INSTALL_CMAKE_PACKAGE "Install cmake package files" ON)
 option(INSTALL_EXAMPLES "Install example files" ON)
 
+option(FUTURE "Include ABI-breaking changes CONSIDERED for the next major release" OFF)
+
 # *** END OPTIONS ***
 
 if(NOT (BUILD_STATIC_LIBS OR BUILD_SHARED_LIBS))
@@ -121,6 +123,10 @@ else()
   set(ENABLE_QTC_ARG --disable-tc)
 endif()
 
+if(FUTURE)
+  add_compile_definitions(QPDF_FUTURE=1)
+endif()
+
 enable_testing()
 set(RUN_QTEST perl ${qpdf_SOURCE_DIR}/run-qtest ${ENABLE_QTC_ARG})
 
@@ -347,6 +353,7 @@ message(STATUS "  build static libraries: ${BUILD_STATIC_LIBS}")
 message(STATUS "  build manual: ${BUILD_DOC}")
 message(STATUS "  compiler warnings are errors: ${WERROR}")
 message(STATUS "  QTC test coverage: ${ENABLE_QTC}")
+message(STATUS "  include future changes: ${FUTURE}")
 message(STATUS "  system: ${CPACK_SYSTEM_NAME}")
 message(STATUS "")
 message(STATUS "*** Options Summary ***")

manual/installation.rst

@@ -277,6 +277,11 @@ BUILD_SHARED_LIBS, BUILD_STATIC_LIBS
   compiled executables can find the DLL. Updating your path is not
   necessary if you build with static libraries only.
 
+FUTURE
+  This option enables changes planned for the next major release to be
+  included. These changes are ABI breaking and are subject to change. They
+  are NOT part of the stable API.
+
 QTEST_COLOR
   Turn this on or off to control whether qtest uses color in its
   output.