Merge pull request #992 from jberkenbilt/future

Future

Merge pull request #992 from jberkenbilt/future
Future
Jay Berkenbilt · GitHub
2 parents 9b09436c 13761120
Showing 5 changed files with 35 additions and 0 deletions
CMakeLists.txt
include/qpdf/QPDFObjectHandle.hh
manual/installation.rst
manual/packaging.rst
manual/release-notes.rst
@@ -104,6 +104,8 @@ option(INSTALL_PKGCONFIG &quot;Install pkgconfig file&quot; 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 &quot;  build static libraries: ${BUILD_STATIC_LIBS}&quot;)
 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 ***")
@@ -290,6 +290,14 @@ class QPDFObjectHandle
     QPDFObjectHandle(QPDFObjectHandle const&) = default;
     QPDF_DLL
     QPDFObjectHandle& operator=(QPDFObjectHandle const&) = default;
+
+#ifdef QPDF_FUTURE
+    QPDF_DLL
+    QPDFObjectHandle(QPDFObjectHandle&&) = default;
+    QPDF_DLL
+    QPDFObjectHandle& operator=(QPDFObjectHandle&&) = default;
+#endif
+
     QPDF_DLL
     inline bool isInitialized() const;
  
@@ -277,6 +277,16 @@ 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. They are NOT part of the stable API. These changes are ABI
+  breaking and are subject to change, which means code linked against
+  a qpdf built with this option may not be binary compatible with
+  installed qpdf libraries. Set this if you want to test your code
+  with proposed QPDF API changes and provide feedback prior to the
+  inclusion of those changes in a release. Packagers should never
+  distribute backages built with this option.
+
 QTEST_COLOR
   Turn this on or off to control whether qtest uses color in its
   output.
@@ -26,6 +26,12 @@ particularly useful to packagers.
   combined with either ``ctest --verbose`` or ``ctest
   --output-on-failure``.
  
+- Packagers should never define the ``FUTURE`` build option. API
+  changes enabled by ``FUTURE`` are not stable and may be
+  API/ABI-breaking. That option is intended only for people who are
+  testing their code with a local build of qpdf to provide early
+  feedback or prepare for possible future changes to the API.
+
 - qpdf's install targets do not install completion files by default
   since there is no standard location for them. As a packager, it's
   good if you install them wherever your distribution expects such
@@ -6,6 +6,10 @@ Release Notes
 For a detailed list of changes, please see the file
 :file:`ChangeLog` in the source distribution.
  
+If you are a developer and want to test your code against future API
+changes that are under consideration, you can build qpdf locally and
+enable the ``FUTURE`` build option (see :ref:`build-options`).
+
 Planned changes for future 12.x (subject to change):
   - ``QPDFObjectHandle`` will support move construction/assignment.
     This change will be invisible to most developers but may break