diff --git a/.gitignore b/.gitignore index 55a89cb..8708f82 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/.idea/.gitignore b/.idea/.gitignore index 55b9763..6fb19b7 100644 --- a/.idea/.gitignore +++ b/.idea/.gitignore @@ -7,3 +7,5 @@ /dataSources/ /dataSources.local.xml /inspectionProfiles +# We use CMakePresets.json. Don't check in cmake profiles. +/cmake.xml diff --git a/.idea/cmake.xml b/.idea/cmake.xml deleted file mode 100644 index 5762463..0000000 --- a/.idea/cmake.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..7036883 --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,204 @@ +{ + "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" + } + } + ] +} diff --git a/README-maintainer.md b/README-maintainer.md index 7ca16a8..c8fb847 100644 --- a/README-maintainer.md +++ b/README-maintainer.md @@ -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 diff --git a/cSpell.json b/cSpell.json index 441767f..36dddda 100644 --- a/cSpell.json +++ b/cSpell.json @@ -612,6 +612,7 @@ "stampfile", "stamppdf", "startxref", + "startxrefs", "stdexcept", "stdint", "stdiofile", diff --git a/manual/release-notes.rst b/manual/release-notes.rst index b718de1..5838002 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -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