diff options
Diffstat (limited to 'manual/packaging.rst')
-rw-r--r-- | manual/packaging.rst | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/manual/packaging.rst b/manual/packaging.rst new file mode 100644 index 00000000..6ff77e51 --- /dev/null +++ b/manual/packaging.rst @@ -0,0 +1,120 @@ +.. _packaging: + +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 :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. + +.. _packaging-doc: + +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 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. + +- **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 + :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 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. + +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 +<https://www.sphinx-doc.org>`__. 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 +:file:`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. |