From 33f207ca74f17763d555031e026c9c0490709976 Mon Sep 17 00:00:00 2001 From: m-holger Date: Wed, 14 Jun 2023 16:30:38 +0100 Subject: [PATCH 1/3] Add FUTURE build option --- CMakeLists.txt | 7 +++++++ manual/installation.rst | 5 +++++ 2 files changed, 12 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index d2ec8ffd..ac0c0435 100644 --- a/CMakeLists.txt +++ b/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 ***") diff --git a/manual/installation.rst b/manual/installation.rst index 7b57ef2a..cef2c9a5 100644 --- a/manual/installation.rst +++ b/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. From 4101596f1ab61af99b71defa2e2b512d52dcc6ea Mon Sep 17 00:00:00 2001 From: m-holger Date: Wed, 14 Jun 2023 18:39:18 +0100 Subject: [PATCH 2/3] Add QPDFObjectHandle move constructor and assignment operator for future build --- include/qpdf/QPDFObjectHandle.hh | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh index 45ad1079..03262b40 100644 --- a/include/qpdf/QPDFObjectHandle.hh +++ b/include/qpdf/QPDFObjectHandle.hh @@ -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; From 13761120b1dbe126a9d39b9439086b76b4860b27 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Sat, 17 Jun 2023 12:20:23 -0400 Subject: [PATCH 3/3] Enhance documentation about FUTURE build option --- manual/installation.rst | 9 +++++++-- manual/packaging.rst | 6 ++++++ manual/release-notes.rst | 4 ++++ 3 files changed, 17 insertions(+), 2 deletions(-) diff --git a/manual/installation.rst b/manual/installation.rst index cef2c9a5..52578dc2 100644 --- a/manual/installation.rst +++ b/manual/installation.rst @@ -279,8 +279,13 @@ BUILD_SHARED_LIBS, BUILD_STATIC_LIBS 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. + 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 diff --git a/manual/packaging.rst b/manual/packaging.rst index 1bd89758..ca32554a 100644 --- a/manual/packaging.rst +++ b/manual/packaging.rst @@ -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 diff --git a/manual/release-notes.rst b/manual/release-notes.rst index dcb626f2..806c5e6e 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -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