diff options
Diffstat (limited to 'manual/packaging.rst')
-rw-r--r-- | manual/packaging.rst | 75 |
1 files changed, 39 insertions, 36 deletions
diff --git a/manual/packaging.rst b/manual/packaging.rst index 6ff77e51..50f8fc60 100644 --- a/manual/packaging.rst +++ b/manual/packaging.rst @@ -9,6 +9,10 @@ chapter is for you. Otherwise, feel free to skip. Build Options ------------- +For a detailed discussion of build options, please refer to +:ref:`build-options`. This section calls attention to options that are +particularly useful to packagers. + - Perl must be present at build time. Prior to qpdf version 9.1.1, there was a runtime dependency on perl, but this is no longer the case. @@ -16,31 +20,23 @@ Build Options - Make sure you are getting the intended behavior with regard to crypto providers. Read :ref:`crypto.build` for details. -- Passing :samp:`--enable-show-failed-test-output` to - :command:`./configure` will cause any failed test - output to be written to the console. This can be very useful for - seeing test failures generated by autobuilders where you can't access - qtest.log after the fact. - -- If qpdf's build environment detects the presence of autoconf and - related tools, it will check to ensure that automatically generated - files are up-to-date with recorded checksums and fail if it detects a - discrepancy. This feature is intended to prevent you from - accidentally forgetting to regenerate automatic files after modifying - their sources. If your packaging environment automatically refreshes - automatic files, it can cause this check to fail. Suppress qpdf's - checks by passing :samp:`--disable-check-autofiles` - to :command:`/.configure`. This is safe since qpdf's - :command:`autogen.sh` just runs autotools in the - normal way. - -- QPDF's :command:`make install` does not install completion files by - default, but as a packager, it's good if you install them wherever - your distribution expects such files to go. You can find completion - files to install in the :file:`completions` directory. - -- Packagers are encouraged to install the source files from the - :file:`examples` directory along with qpdf development packages. +- Use of ``SHOW_FAILED_TEST_OUTPUT`` is recommended for building in + continuous integration or other automated environments as it makes + it possible to see test failures in build logs. This should be + combined with either ``ctest --verbose`` or ``ctest + --output-on-failure``. + +- 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 + files to go. You can find completion files to install in the + :file:`completions` directory. See the :file:`completions/README.md` + file for more information. + +- Starting with qpdf 11, qpdf's default installation installs source + files from the examples directory with documentation. Prior to qpdf + 11, this was a recommendation for packagers but was not done + automatically. .. _packaging-doc: @@ -54,27 +50,34 @@ you may want to consider for your packages: - **Do nothing** When you run ``make install``, the file :file:`README-doc.txt` is - installed in ``$(docdir)``. That file tells the reader where to find - the documentation online and where to go to download offline copies - of the documentation. This is the option selected by the debian - packages. + installed in the documentation directory. That file tells the reader + where to find the documentation online and where to go to download + offline copies of the documentation. This is the option selected by + the debian packages. - **Embed pre-built documentation** You can obtain pre-built documentation and extract its contents into your distribution. This is what the Windows binary distributions - available from the qpdf release site do. You can find the pre-build + available from the qpdf release site do. You can find the pre-built documentation in the release area in the file - :file:`qpdf-{version}-doc.zip`. + :file:`qpdf-{version}-doc.zip`. For an example of this approach, + look at qpdf's GitHub actions build scripts. The + :file:`build-scripts/build-doc` script builds with + ``-DBUILD_DOC_DIST=1`` to create the documentation distribution. The + :file:`build-scripts/build-windows` script extracts it into the + build tree and builds with ``-DINSTALL_MANUAL=1`` to include it in + the installer. - **Build the documentation yourself** You can build the documentation as part of your build process. Be - sure to pass ``--enable-doc-maintenance`` to ``./configure``, and - install it with ``make doc-dist DOC_DEST=...``. This is what the - AppImage build does. The latest version of Sphinx at the time of the - initial conversion a sphinx-based documentation was 4.3.2. Older - versions are not guaranteed to work. + sure to pass ``-DBUILD_DOC_DIST=1`` and ``-DINSTALL_MANUAL=1`` to + cmake. This is what the AppImage build does. The latest version of + Sphinx at the time of the initial conversion a sphinx-based + documentation was 4.3.2. Older versions are not guaranteed to work. + +.. _doc-packaging-rationale: Documentation Packaging Rationale ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |