Notes for Packagers
If you are packaging qpdf for an operating system distribution, this chapter is for you. Otherwise, feel free to skip.
Build Options
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.
Make sure you are getting the intended behavior with regard to crypto providers. Read Build Support For Crypto Providers for details.
Passing
--enable-show-failed-test-output
to ./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
--disable-check-autofiles
to /.configure. This is safe since qpdf’s autogen.sh just runs autotools in the normal way.QPDF’s 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
completions
directory.Packagers are encouraged to install the source files from the
examples
directory along with qpdf development packages.
Packaging Documentation
Starting in qpdf version 10.5, pre-built documentation is no longer distributed with the qpdf source distribution. Here are a few options you may want to consider for your packages:
Do nothing
When you run
make install
, the fileREADME-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.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 documentation in the release area in the file
qpdf-version-doc.zip
.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 withmake 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.
Documentation Packaging Rationale
This section describes the reason for things being the way they are. It’s for information only; you don’t have to know any of this to package qpdf.
What is the reason for this change? Prior to qpdf 10.5, the qpdf
manual was a docbook XML file. The generated documents were the
product of running the file through build-time style sheets and
contained no copyrighted material of their own. Starting with version
10.5, the manual is written produced with Sphinx. This change was made to make it much
easier to automatically generate portions of the documentation and to
make the documentation easier to work with. The HTML output of Sphinx
is also much more readable, usable, and suitable for online
consumption than the output of the docbook style sheets. The downsides
are that the generated HTML documentation now contains Javascript code
and embedded fonts, and the PDF version of the documentation is no
longer as suitable for printing (at least as of the 10.5 distribution)
since external link targets are no longer shown and cross references
no longer contain page number information. The presence of copyrighted
material in the generated documentation, even though things are
licensed with MIT and BSD licenses, complicates the job of the
packager in various ways. For one thing, it means the
NOTICE.md
file in the source repository would have to keep up
with the copyright information for files that are not controlled in
the repository. Additionally, some distributions (notably
Debian/Ubuntu) discourage inclusion of sphinx-generated documentation
in packages, preferring you instead to build the documentation as part
of the package build process and to depend at runtime on a shared
package that contains the code. At the time of the conversion of the
qpdf manual from docbook to sphinx, newer versions of both sphinx and
the html theme were required than were available in some of most of
the Debian/Ubuntu versions for which qpdf was packaged.
Since always-on Internet connectivity is much more common than it used to be, many users of qpdf would prefer to consume the documentation online anyway, and the lack of pre-built documentation in the distribution won’t be as big of a deal. However there are still some people who can’t or choose not to view documentation online. For them, pre-built documentation is still available.