Replace JetBrains-specific cmake profiles with CMakePresets.json

Plus sneak in some spell checks

Replace JetBrains-specific cmake profiles with CMakePresets.json
Plus sneak in some spell checks
Jay Berkenbilt
1 parent 6434e09d
Showing 7 changed files with 273 additions and 45 deletions
.gitignore
.idea/.gitignore
.idea/cmake.xml
CMakePresets.json
README-maintainer.md
cSpell.json
manual/release-notes.rst
@@ -7,3 +7,8 @@ appimage/build
 .cache
 /html
 Doxyfile
+/CMakeUserPresets.json
+/compile_commands.json
+
+# ./Testing is created if you run ctest from the wrong place.
+/Testing
@@ -7,3 +7,5 @@
 /dataSources/
 /dataSources.local.xml
 /inspectionProfiles
+# We use CMakePresets.json. Don't check in cmake profiles.
+/cmake.xml
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="CMakeSharedSettings">
-    <configurations>
-      <configuration PROFILE_NAME="Maintainer" ENABLED="true" CONFIG_NAME="RelWithDebInfo" GENERATION_OPTIONS="-DMAINTAINER_MODE=ON -DBUILD_STATIC_LIBS=OFF" />
-      <configuration PROFILE_NAME="Windows" ENABLED="true" CONFIG_NAME="RelWithDebInfo" TOOLCHAIN_NAME="Visual Studio" GENERATION_OPTIONS="-DBUILD_SHARED_LIBS=OFF" />
-    </configurations>
-  </component>
-</project>
 \ No newline at end of file
+{
+  "version": 3,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 19,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "base-config",
+      "hidden": true,
+      "description": "Common base settings",
+      "binaryDir": "${sourceDir}/cmake-build-${presetName}",
+      "cacheVariables": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    },
+    {
+      "name": "base-debug",
+      "hidden": true,
+      "inherits": "base-config",
+      "description": "Base settings for debug builds",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "BUILD_SHARED_LIBS": "OFF"
+      }
+    },
+    {
+      "name": "base-unix",
+      "hidden": true,
+      "inherits": "base-config",
+      "description": "Base settings for Linux & macOS",
+      "condition": {
+        "type": "anyOf",
+        "conditions": [
+          {
+            "type": "equals",
+            "lhs": "${hostSystemName}",
+            "rhs": "Linux"
+          },
+          {
+            "type": "equals",
+            "lhs": "${hostSystemName}",
+            "rhs": "Darwin"
+          }
+        ]
+      },
+      "generator": "Ninja"
+    },
+    {
+      "name": "base-msvc",
+      "hidden": true,
+      "inherits": "base-config",
+      "description": "Base settings for Windows using MSVC",
+      "environment": {
+        "TOOLCHAIN_NAME": "Visual Studio"
+      },
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Windows"
+      }
+    },
+    {
+      "name": "base-maintainer",
+      "hidden": true,
+      "displayName": "Base settings for maintainer mode",
+      "description": "Unix Maintainer build",
+      "inherits": "base-unix",
+      "cacheVariables": {
+        "MAINTAINER_MODE": "ON",
+        "BUILD_STATIC_LIBS": "OFF"
+      }
+    },
+    {
+      "name": "maintainer",
+      "displayName": "Maintainer",
+      "description": "Unix Maintainer build",
+      "inherits": "base-maintainer",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo"
+      }
+    },
+    {
+      "name": "maintainer-debug",
+      "displayName": "Maintainer (debug)",
+      "description": "Unix Maintainer build",
+      "inherits": [
+        "base-maintainer",
+        "base-debug"
+      ],
+      "cacheVariables": {
+        "BUILD_STATIC_LIBS": "ON"
+      }
+    },
+    {
+      "name": "maintainer-coverage",
+      "displayName": "Maintainer (coverage)",
+      "description": "Unix Maintainer build",
+      "inherits": "maintainer-debug",
+      "cacheVariables": {
+        "ENABLE_COVERAGE": "ON"
+      }
+    },
+    {
+      "name": "maintainer-profile",
+      "displayName": "Maintainer (profile)",
+      "description": "Unix Maintainer build",
+      "inherits": "maintainer-debug",
+      "environment": {
+        "CFLAGS": "-pg",
+        "CXXFLAGS": "-pg",
+        "LDFLAGS": "-pg"
+      }
+    },
+    {
+      "name": "debug",
+      "displayName": "Debug",
+      "description": "Debug build",
+      "inherits": "base-config",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    },
+    {
+      "name": "release",
+      "displayName": "Release",
+      "description": "Release build",
+      "inherits": "base-config",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "sanitizers",
+      "displayName": "Unix + clang sanitizers",
+      "description": "Debug build with AddressSanitizer enabled",
+      "inherits": [
+        "base-unix",
+        "debug"
+      ],
+      "environment": {
+        "CFLAGS": "-fsanitize=address -fsanitize=undefined",
+        "CXXFLAGS": "-fsanitize=address -fsanitize=undefined",
+        "LDFLAGS": "-fsanitize=address -fsanitize=undefined",
+        "CC": "clang",
+        "CXX": "clang++"
+      },
+      "cacheVariables": {
+        "MAINTAINER_MODE": "ON",
+        "BUILD_SHARED_LIBS": "OFF",
+        "REQUIRE_CRYPTO_OPENSSL": "ON",
+        "REQUIRE_CRYPTO_GNUTLS": "ON",
+        "ENABLE_QTC": "ON"
+      }
+    },
+    {
+      "name": "msvc",
+      "displayName": "Windows/MSVC",
+      "description": "Visual Studio release with debug info build",
+      "inherits": [
+        "base-msvc"
+      ],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "BUILD_SHARED_LIBS": "OFF"
+      }
+    },
+    {
+      "name": "msvc-release",
+      "displayName": "Windows/MSVC Release",
+      "description": "Visual Studio release build",
+      "inherits": [
+        "base-msvc",
+        "release"
+      ]
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "maintainer",
+      "configurePreset": "maintainer",
+      "description": "Run build for maintainer mode"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "maintainer",
+      "configurePreset": "maintainer",
+      "description": "Run default tests for maintainer mode",
+      "output": {
+        "verbosity": "verbose"
+      }
+    },
+    {
+      "name": "msvc",
+      "configurePreset": "msvc",
+      "description": "Run default tests for msvc",
+      "output": {
+        "verbosity": "verbose"
+      }
+    }
+  ]
+}
@@ -30,70 +30,85 @@ separate mechanism for tracking changes.
 **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:
+Run `cmake --list-presets` to see available cmake presets. Routine maintainer development can be
 ```
-cmake -DMAINTAINER_MODE=ON -DBUILD_STATIC_LIBS=OFF \
-   -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
+cmake --preset maintainer
+cmake --build --preset maintainer
+ctest --preset maintainer
 ```
-Debugging:
+See [CMakePresets.json](CMakePresets.json) for additional presets. Reminders about presets:
+* You can override/enhance configure presets, e.g., `cmake --preset maintainer -DCMAKE_BUILD_TYPE=Release`
+* You can pass flags to ctest, e.g., `ctest --preset maintainer -R zlib-flate`.
+* You can't override the build directory for build and test presets, but you _can_ override the
+  directory for configure presets and then run `cmake --build build-dir` and `ctest` manually, as
+  shown below.
+* The base configuration includes `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`, which is useful for LSP mode
+  in C++. This is harmless in environments where it's not needed. You may need to make a symlink
+  from compile_commands.json to the one in whichever build directory you are using.
+* If you have common configurations you'd like to see, pull requests are welcome, but
+  `CMakeUserPresets.json` is your friend. You can copy or inherit from CMakeUserPresets.json for
+  your own use. Note that CMakeUserPresets.json is not part of the stable API. We reserve the right
+  to modify these presets in a non-compatible fashion at any time without regard to qpdf version
+  numbers, but we should mention changes in the release notes.
+* Study the CMakePresets.json file for details on how these are implemented.
+
+See also ./build-scripts for other ways to run the build for different configurations.
+
+### Useful build examples
+
+To run a maintainer build in release mode and run only the unicode-filenames test, you could run
 ```
-cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
-   -DCMAKE_BUILD_TYPE=Debug ..
+cmake --preset maintainer -DCMAKE_BUILD_TYPE=Release
+cmake --build --preset maintainer
+TESTS=unicode-filenames ctest --preset maintainer -R qpdf
 ```
-Profiling:
+To run a maintainer build in release mode in a _different directory_ and run only the
+unicode-filenames test, you could run the following. Trying to override the directory on the command
+line of `cmake --build` or `ctest` in conjunction with `--preset` may silently ignore the directory
+override, and you may not get what you think you are getting.
 ```
-CFLAGS=-pg LDFLAGS=-pg \
-   cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
-   -DCMAKE_BUILD_TYPE=Debug ..
+cmake --preset maintainer -DCMAKE_BUILD_TYPE=Release -B cmake-build-release
+cmake --build cmake-build-release
+TESTS=unicode-filenames ctest --verbose --test-dir cmake-build-release -R qpdf
 ```
-Then run `gprof gmon.out`. Note that gmon.out is not cumulative.
+### Profiling
-Coverage:
+When running with the `maintainer-profile` preset (or any time you run profiling), run `gprof
+gmon.out`. Note that gmon.out is not cumulative.
-```
-cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
-   -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON..
-```
+### Coverage
-Then, from the build directory, run the test suite (`ctest --verbose`) followed by
+When running with the `maintainer-coverage` preset, after running tests:
 ```
 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:
+### Sanitizers/Memory Checks
-Note: if clang++ fails to create output, it may be necessary to install a specific version of
-libstdc++-dev. For example, with clang++ version 20 on Ubuntu 24.04, `clang++ -v` indicates the
-selected GCC installation is 14, so it is necessary to install `libstdc++-14-dev`.
+If `clang++` fails to create output during configuration, it may be necessary to install a specific
+version of libstdc++-dev. For example, with clang++ version 20 on Ubuntu 24.04, `clang++ -v`
+indicates the selected GCC installation is 14, so it is necessary to install `libstdc++-14-dev`.
-```
-CFLAGS="-fsanitize=address -fsanitize=undefined" \
-   CXXFLAGS="-fsanitize=address -fsanitize=undefined" \
-   LDFLAGS="-fsanitize=address -fsanitize=undefined" \
-   CC=clang CXX=clang++ \
-   cmake -DMAINTAINER_MODE=ON -DBUILD_SHARED_LIBS=OFF \
-   -DCMAKE_BUILD_TYPE=Debug ..
-```
+### Windows
-Windows:
+You can use this for command-line builds, which does a bit more than the presets. The msvc presets
+are known to work in CLion if the environment is set up as described in
+[README-windows.md](./README-windows.md), but for regular command-line builds (and CI), continue to
+use `cmake-win` from inside a build directory. Look at `build-scripts/build-windows` to see how this
+is used.
 ```
 ../cmake-win {mingw|msvc} maint
 ```
-See ./build-scripts for other ways to run the build for different
-configurations.
-
 ## VERSIONS
 * The version number on the main branch is whatever the version would
@@ -612,6 +612,7 @@
     "stampfile",
     "stamppdf",
     "startxref",
+    "startxrefs",
     "stdexcept",
     "stdint",
     "stdiofile",
@@ -21,7 +21,7 @@ more detail.
       integer object. Previously the method returned false if the first
       dictionary object was not a linearization parameter dictionary.
-    - Fix parsing of object streams containing objects not seperated by
+    - Fix parsing of object streams containing objects not separated by
       white-space. Pre-2020 editions of the PDF specification incorrectly
       stated that white-space was required between objects. qpdf relied on this
       when parsing object streams.
@@ -39,6 +39,16 @@ more detail.
     - There have been further enhancements to how files with damaged xref
       tables are recovered.
+  - Build changes
+
+    - The file ``.idea/cmake.xml`` has been removed. Instead of
+      shipping with some CMake profiles in the CLion-specific
+      configuration, we now include a ``CMakePresets.json``. There is
+      information about using it in ``README-maintainer.md``. For
+      most users, running ``cmake`` in the normal way is fine.
+      Suggestions are welcome. None of the official builds use cmake
+      presets at the time of initial introduction.
+
   - Other changes
     - The parsing of object streams including the creation of error/warning