/
installation.rst
267 lines (181 loc) · 8.78 KB
/
installation.rst
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
Installation
============
Basic installation
------------------
.. |latest| image:: https://img.shields.io/pypi/v/pikepdf.svg
:alt: pikepdf latest released version on PyPI
|latest|
Most users on Linux, macOS or Windows with x64 systems should use ``pip`` to
install pikepdf in their current Python environment (such as your project's
virtual environment).
.. code-block:: bash
pip install pikepdf
Use ``pip install --user pikepdf`` to install the package for the current user
only. Use ``pip install pikepdf`` to install to a virtual environment.
**Linux users:** If you have an older version of ``pip``, such as the one that ships
with Ubuntu 18.04, this command will attempt to compile the project instead of
installing the wheel. If you want to get the binary wheel, upgrade ``pip`` with:
.. code-block:: bash
wget https://bootstrap.pypa.io/get-pip.py && python3 get-pip.py
pip --version # should be 20.0 or newer
pip install pikepdf
Binary wheel availability
-------------------------
.. csv-table:: Python binary wheel availability
:file: binary-wheels.csv
:header-rows: 1
\* *Apple Silicon is supported on a best-effort by manually uploading. These
releases sometimes come a few days later.*
Binary wheels should work on most systems, **provided a recent version
of pip is used to install them**. Old versions of pip, especially before 20.0,
may fail to check appropriate versions.
macOS 10.14 or newer is typically required for binary wheels. Older versions may
work if compiled from source.
Windows 7 or newer is required. Windows wheels include a recent copy of libqpdf.
Most Linux distributions support manylinux2010, with the notable except of
`Alpine Linux`_, and older Linux distributions that do not have C++14-capable
compilers. The Linux wheels include recent copies of libqpdf, libjpeg, and zlib.
Platform support
----------------
Some platforms include versions of pikepdf that are distributed by the system
package manager (such as ``apt``). These versions may lag behind the version
distributed with PyPI, but may be convenient for users that cannot use binary
wheels.
.. figure:: /images/sushi.jpg
:align: right
:alt: Bento box containing sushi
:figwidth: 40%
Packaged fish.
.. |python-pikepdf| image:: https://repology.org/badge/vertical-allrepos/python:pikepdf.svg
:alt: Package status for python:pikepdf
|python-pikepdf|
Debian, Ubuntu and other APT-based distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
apt install pikepdf
Fedora
^^^^^^
.. |fedora| image:: https://repology.org/badge/version-for-repo/fedora_rawhide/python:pikepdf.svg
:alt: Fedora Rawhide
|fedora|
.. code-block:: bash
dnf install python-pikepdf
Alpine Linux
^^^^^^^^^^^^
.. |alpine| image:: https://repology.org/badge/version-for-repo/alpine_edge/python:pikepdf.svg
:alt: Alpine Linux Edge
|alpine|
.. code-block:: bash
apk add py3-pikepdf
Installing on FreeBSD
---------------------
.. |freebsd| image:: https://repology.org/badge/version-for-repo/freebsd/python:pikepdf.svg
:alt: FreeBSD
:target: https://repology.org/project/python:pikepdf/versions
.. code-block:: bash
pkg install py38-pikepdf
To attempt a manual install, try something like:
.. code-block:: bash
pkg install python3 py38-lxml py38-pip py38-pybind11 qpdf
pip install --user pikepdf
This procedure is known to work on FreeBSD 11.3, 12.0, 12.1-RELEASE and
13.0-CURRENT. It has not been tested on other versions.
Building from source
--------------------
**Requirements**
.. |qpdf-version| replace:: 10.0.3
pikepdf requires:
- a C++14 compliant compiler - GCC (5 and up), clang (3.3 and up), MSVC
(2015 or newer)
- `pybind11 <https://github.com/pybind/pybind11>`_
- libqpdf |qpdf-version| or higher from the
`QPDF <https://github.com/qpdf/qpdf>`_ project.
On Linux the library and headers for libqpdf must be installed because pikepdf
compiles code against it and links to it.
Check `Repology for QPDF <https://repology.org/project/qpdf/badges>`_ to
see if a recent version of QPDF is available for your platform. Otherwise you
must
`build QPDF from source <https://github.com/qpdf/qpdf/blob/master/INSTALL>`_.
(Consider using the binary wheels, which bundle the required version of
libqpdf.)
**Compiling with GCC or Clang**
- clone this repository
- install libjpeg, zlib and libqpdf on your platform, including headers
- ``pip install .``
.. note::
pikepdf should be built with the same compiler and linker as libqpdf; to be
precise both **must** use the same C++ ABI. On some platforms, setup.py may
not pick the correct compiler so one may need to set environment variables
``CC`` and ``CXX`` to redirect it. If the wrong compiler is selected,
``import pikepdf._qpdf`` will throw an ``ImportError`` about a missing
symbol.
**On Windows (requires Visual Studio 2015)**
.. |msvc-zip| replace:: qpdf-|qpdf-version|-bin-msvc64.zip
pikepdf requires a C++14 compliant compiler (i.e. Visual Studio 2015 on
Windows). See our continuous integration build script in ``.appveyor.yml``
for detailed and current instructions. Or use the wheels which save this pain.
These instructions require the precompiled binary ``qpdf.dll``. See the QPDF
documentation if you also need to build this DLL from source. Both should be
built with the same compiler. You may not mix and match MinGW and Visual C++
for example.
Running a regular ``pip install`` command will detect the
version of the compiler used to build Python and attempt to build the
extension with it. We must force the use of Visual Studio 2015.
#. Clone this repository.
#. In a command prompt, run:
.. code-block:: bat
%VS140COMNTOOLS%\..\..\VC\vcvarsall.bat" x64
set DISTUTILS_USE_SDK=1
set MSSdk=1
#. Download |msvc-zip| from the `QPDF releases page <https://github.com/qpdf/qpdf/releases>`_.
#. Extract ``bin\*.dll`` (all the DLLs, both QPDF's and the Microsoft Visual C++
Runtime library) from the zip file above, and copy it to the ``src/pikepdf``
folder in the repository.
#. Run ``pip install .`` in the root directory of the repository.
.. note::
The user compiling ``pikepdf`` to must have registry editing rights on the
machine to be able to run the ``vcvarsall.bat`` script.
**Building against a QPDF source tree**
Follow these steps to build pikepdf against a different version of QPDF, rather than
the one provided with your operating system. This may be useful if you need a more
recent version of QPDF than your operating system package manager provides, and you
do not want to use Python wheels.
* Set the environment variable ``QPDF_SOURCE_TREE`` to the location of the QPDF source
tree.
* Build QPDF, by running ``make``. Refer to the QPDF installation instructions for
further options and details.
* On Linux, modify ``LD_LIBRARY_PATH``, prepending the path where the QPDF build
produces ``libqpdfXX.so``. This might be something like
``$QPDF_SOURCE_TREE/.build/libs/libqpdfXX.so``. On macOS, locate the equivalent
variable is ``DYLD_LIBRARY_PATH``. On Windows, no action is needed. Generally,
what you are doing here is telling the runtime dynamic linker to use the custom
compiled version of QPDF instead of the system version.
* Build pikepdf. On Windows, locate the QPDF .dll files and copy them into the folder
alongside the file named ``_qpdf*.dll``.
Note that the Python wheels for pikepdf currently compile their own version of
QPDF and several of its dependencies to ensure the wheels have the latest version.
You can also refer to the GitHub Actions YAML files for build steps.
**Building against a custom install of QPDF to /usr/local/lib**
If you have previously installed a QPDF from source to ``/usr/local/lib`` on
a POSIX platform, and you try to build pikepdf from source, it will prefer the
operating system version of QPDF installed at ``/usr/lib``. Since pikepdf strongly
prefers recent versions of QPDF, you may want to use a more current version.
From a Git checkout of the pikepdf source tree, run:
.. code-block:: bash
env LDFLAGS='-L/usr/local/lib' CFLAGS='-I/usr/local/include/qpdf' pip install .
Building the documentation
--------------------------
Documentation is generated using Sphinx and you are currently reading it. To
regenerate it:
.. code-block:: bash
pip install pikepdf[docs]
cd docs
make html
PyPy3 support
-------------
PyPy3 3.6 and 3.7 are currently supported, these being the latest versions of PyPy
as of this writing. Windows PyPy wheels are not supported because cibuildwheel
does not support Windows 64-bit PyPy. We have not checked if source builds work.
PyPy3 is not more performant than CPython for pikepdf, because the core of pikepdf
is already written in C++. The benefit is for applications that want to use PyPy
for improved performance of native Python and also want to use pikepdf.