Add ENABLE_COVERAGE option to build

6 files changed, 45 insertions, 11 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 89a28302..8a3d5f5a 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -72,6 +72,7 @@ CMAKE_DEPENDENT_OPTION(
   BUILD_DOC_DIST "Create distribution of manual" ON
   "BUILD_DOC_PDF;BUILD_DOC_HTML" OFF)
 
+option(ENABLE_COVERAGE "Enable coverage reporting" OFF)
 option(BUILD_SHARED_LIBS "Build qpdf shared libraries" ON)
 option(BUILD_STATIC_LIBS "Build qpdf static libraries" ON)
 option(QTEST_COLOR "Whether qtest's output should be in color" ON)
@@ -296,6 +297,11 @@ set(CPACK_RESOURCE_FILE_LICENSE "${qpdf_SOURCE_DIR}/LICENSE.txt")
 set(CPACK_PACKAGE_HOMEPAGE_URL "https://qpdf.sourceforge.io/")
 set(CPACK_NSIS_MUI_ICON "${qpdf_SOURCE_DIR}/logo/qpdf.ico")
 
+if(ENABLE_COVERAGE)
+  add_compile_options(--coverage -O0)
+  add_link_options(--coverage)
+endif()
+
 include(CPack)
 
 # Install components -- documented in _installation in
diff --git a/ChangeLog b/ChangeLog
index 294aa8cc..890d0f99 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2024-02-17  Jay Berkenbilt  <ejb@ql.org>
+
+	* Add ENABLE_COVERAGE cmake option to assist with generating
+	coverage reports.
+
+	* From M. Holger: add QPDFObjectHandle::writeJSON to directly
+	write a JSON representation to a pipeline. This is much faster
+	than writing the serialized result of getJSON.
+
 2024-02-11  Jay Berkenbilt  <ejb@ql.org>
 
 	* The previous fix to #1056 was incomplete. When setting a check
diff --git a/README-maintainer.md b/README-maintainer.md
index 59c6794c..df1656b3 100644
--- a/README-maintainer.md
+++ b/README-maintainer.md
@@ -25,19 +25,19 @@
 
 **Remember to check pull requests as well as issues in github.**
 
+Include `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` with cmake if using emacs lsp mode.
+
 Default:
 
 ```
-cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-   -DMAINTAINER_MODE=ON -DBUILD_STATIC_LIBS=OFF \
+cmake -DMAINTAINER_MODE=ON -DBUILD_STATIC_LIBS=OFF \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
 ```
 
 Debugging:
 
 ```
-cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-   -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
+cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
    -DCMAKE_BUILD_TYPE=Debug ..
 ```
 
@@ -45,13 +45,26 @@ Profiling:
 
 ```
 CFLAGS=-pg LDFLAGS=-pg \
-   cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-   -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
+   cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
    -DCMAKE_BUILD_TYPE=Debug ..
 ```
 
 Then run `gprof gmon.out`. Note that gmon.out is not cumulative.
 
+Coverage:
+
+```
+cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
+   -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON..
+```
+
+Then, from the build directory, run the test suite (`ctest --verbose`) followed by
+```
+gcovr -r .. --html --html-details -o coverage-report.html
+```
+
+Note that, in early 2024, branch coverage information is not very accurate with C++.
+
 Memory checks:
 
 ```
@@ -59,8 +72,7 @@ CFLAGS="-fsanitize=address -fsanitize=undefined" \
    CXXFLAGS="-fsanitize=address -fsanitize=undefined" \
    LDFLAGS="-fsanitize=address -fsanitize=undefined" \
    CC=clang CXX=clang++ \
-   cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-   -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
+   cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
    -DCMAKE_BUILD_TYPE=Debug ..
 ```
 
@@ -691,8 +703,7 @@ export QPDF_BUILD_LIBDIR=$QPDF_SOURCE_TREE/build/libqpdf
 export LD_LIBRARY_PATH=$QPDF_BUILD_LIBDIR
 cd qpdf
 mkdir build
-cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-   -DMAINTAINER_MODE=ON -DBUILD_STATIC_LIBS=OFF \
+cmake -B build -DMAINTAINER_MODE=ON -DBUILD_STATIC_LIBS=OFF \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo
 cat <<'EOF'
 #!/bin/bash
diff --git a/job.sums b/job.sums
index 1da9f07b..dddf5fa3 100644
--- a/job.sums
+++ b/job.sums
@@ -1,5 +1,5 @@
 # Generated by generate_auto_job
-CMakeLists.txt f53d67f8c6ace1a2fb63dd9a963ead6b5cd698556f9d0adef2c10744a565b54f
+CMakeLists.txt 9bfd82a7d225b88760ff5af211f9af35a0d9fcdd40fa15fdf7fc820944c2d5f9
 generate_auto_job f64733b79dcee5a0e3e8ccc6976448e8ddf0e8b6529987a66a7d3ab2ebc10a86
 include/qpdf/auto_job_c_att.hh 4c2b171ea00531db54720bf49a43f8b34481586ae7fb6cbf225099ee42bc5bb4
 include/qpdf/auto_job_c_copy_att.hh 50609012bff14fd82f0649185940d617d05d530cdc522185c7f3920a561ccb42
diff --git a/manual/installation.rst b/manual/installation.rst
index 7f95f3d9..e49a87eb 100644
--- a/manual/installation.rst
+++ b/manual/installation.rst
@@ -302,6 +302,10 @@ CHECK_SIZES
   that ensures an exact match between classes in ``sizes.cc`` and
   classes in the library's public API. This option requires Python 3.
 
+ENABLE_COVERAGE
+  Compile with ``--coverage``. See README-maintainer.md for
+  information about generating coverage reports.
+
 ENABLE_QTC
   This is off by default, except in maintainer mode. When off,
   ``QTC::TC`` calls are compiled out by having ``QTC::TC`` be an empty
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index b9f7d14b..209e9181 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -60,6 +60,10 @@ Planned changes for future 12.x (subject to change):
     - Add ``file()``, ``range()``, and ``password()`` to
       ``QPDFJob::PagesConfig`` as an alternative to ``pageSpec``.
 
+    - Add ``QPDFObjectHandle::writeJSON`` to write the JSON
+      representation of the object directly to a pipeline. This is
+      much faster than calling ``QPDFObjectHandle::getJSON``.
+
 11.8.0: January 8, 2024
   - Bug fixes: