Commit 13761120b1dbe126a9d39b9439086b76b4860b27
1 parent
4101596f
Enhance documentation about FUTURE build option
Showing
3 changed files
with
17 additions
and
2 deletions
manual/installation.rst
| @@ -279,8 +279,13 @@ BUILD_SHARED_LIBS, BUILD_STATIC_LIBS | @@ -279,8 +279,13 @@ BUILD_SHARED_LIBS, BUILD_STATIC_LIBS | ||
| 279 | 279 | ||
| 280 | FUTURE | 280 | FUTURE |
| 281 | This option enables changes planned for the next major release to be | 281 | This option enables changes planned for the next major release to be |
| 282 | - included. These changes are ABI breaking and are subject to change. They | ||
| 283 | - are NOT part of the stable API. | 282 | + included. They are NOT part of the stable API. These changes are ABI |
| 283 | + breaking and are subject to change, which means code linked against | ||
| 284 | + a qpdf built with this option may not be binary compatible with | ||
| 285 | + installed qpdf libraries. Set this if you want to test your code | ||
| 286 | + with proposed QPDF API changes and provide feedback prior to the | ||
| 287 | + inclusion of those changes in a release. Packagers should never | ||
| 288 | + distribute backages built with this option. | ||
| 284 | 289 | ||
| 285 | QTEST_COLOR | 290 | QTEST_COLOR |
| 286 | Turn this on or off to control whether qtest uses color in its | 291 | Turn this on or off to control whether qtest uses color in its |
manual/packaging.rst
| @@ -26,6 +26,12 @@ particularly useful to packagers. | @@ -26,6 +26,12 @@ particularly useful to packagers. | ||
| 26 | combined with either ``ctest --verbose`` or ``ctest | 26 | combined with either ``ctest --verbose`` or ``ctest |
| 27 | --output-on-failure``. | 27 | --output-on-failure``. |
| 28 | 28 | ||
| 29 | +- Packagers should never define the ``FUTURE`` build option. API | ||
| 30 | + changes enabled by ``FUTURE`` are not stable and may be | ||
| 31 | + API/ABI-breaking. That option is intended only for people who are | ||
| 32 | + testing their code with a local build of qpdf to provide early | ||
| 33 | + feedback or prepare for possible future changes to the API. | ||
| 34 | + | ||
| 29 | - qpdf's install targets do not install completion files by default | 35 | - qpdf's install targets do not install completion files by default |
| 30 | since there is no standard location for them. As a packager, it's | 36 | since there is no standard location for them. As a packager, it's |
| 31 | good if you install them wherever your distribution expects such | 37 | good if you install them wherever your distribution expects such |
manual/release-notes.rst
| @@ -6,6 +6,10 @@ Release Notes | @@ -6,6 +6,10 @@ Release Notes | ||
| 6 | For a detailed list of changes, please see the file | 6 | For a detailed list of changes, please see the file |
| 7 | :file:`ChangeLog` in the source distribution. | 7 | :file:`ChangeLog` in the source distribution. |
| 8 | 8 | ||
| 9 | +If you are a developer and want to test your code against future API | ||
| 10 | +changes that are under consideration, you can build qpdf locally and | ||
| 11 | +enable the ``FUTURE`` build option (see :ref:`build-options`). | ||
| 12 | + | ||
| 9 | Planned changes for future 12.x (subject to change): | 13 | Planned changes for future 12.x (subject to change): |
| 10 | - ``QPDFObjectHandle`` will support move construction/assignment. | 14 | - ``QPDFObjectHandle`` will support move construction/assignment. |
| 11 | This change will be invisible to most developers but may break | 15 | This change will be invisible to most developers but may break |