1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
.. _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
-------------
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.
- Make sure you are getting the intended behavior with regard to crypto
providers. Read :ref:`crypto.build` for details.
- 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``.
- Packagers should never define the ``FUTURE`` build option. API
changes enabled by ``FUTURE`` are not stable and may be
API/ABI-breaking. That option is intended only for people who are
testing their code with a local build of qpdf to provide early
feedback or prepare for possible future changes to the API.
- 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.
.. _package-tests:
Package Tests
-------------
The :file:`pkg-test` directory contains very small test shell scripts
that are designed to help smoke-test an installation of qpdf. They
were designed to be used with debian's `autopkgtest
<https://wiki.debian.org/ContinuousIntegration/autopkgtest>`__
framework but can be used by others. Please see
:file:`pkg-test/README.md` in the source distribution for details.
.. _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 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-built
documentation in the release area in the file
: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 ``-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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 in reStructured Text and built 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.
|
