Debian Codegraph @

podofo/README.md

raw
1 # PoDoFo [![build-linux](https://github.com/podofo/podofo/actions/workflows/build-linux.yml/badge.svg)](https://github.com/podofo/podofo/actions/workflows/build-linux.yml) [![build-mac](https://github.com/podofo/podofo/actions/workflows/build-mac.yml/badge.svg)](https://github.com/podofo/podofo/actions/workflows/build-mac.yml) [![build-win](https://github.com/podofo/podofo/actions/workflows/build-win.yml/badge.svg)](https://github.com/podofo/podofo/actions/workflows/build-win.yml)
2
3 1. [What is PoDoFo?](#what-is-podofo)
4 2. [Features](#features)
5 3. [Requirements](#requirements)
6 4. [Licensing](#licensing)
7 5. [Development quickstart](#development-quickstart)
8 6. [Doxygen Documentation](#doxygen-documentation)
9 7. [Software life cycle and API stability](#software-life-cycle-and-api-stability)
10 8. [String encoding and buffer conventions](#string-encoding-and-buffer-conventions)
11 9. [Thread safety](#thread-safety)
12 11. [PoDoFo tools](#podofo-tools)
13 12. [TODO](#todo)
14 13. [FAQ](#faq)
15 14. [No warranty](#no-warranty)
16 15. [Contributions](#contributions)
17 16. [Authors](#authors)
18
19 ## What is PoDoFo?
20
21 PoDoFo is a free portable C++ library to work with the PDF file format.
22
23 PoDoFo provides classes to parse a PDF file and modify its content, allowing to write
24 it back to disk easily. Besides PDF parsing and manipulation PoDoFo also provides
25 facilities to create your own PDF files from scratch.
26
27 ## Features
28
29 PoDoFo has a modern and user-friendly C++17 API that features:
30
31 - PDF parsing with high-level entity inspection (annotations, form fields and others)
32 - PDF writing with support for incremental updates
33 - PDF signing with [PAdES-B](https://en.wikipedia.org/wiki/PAdES) compliance,
34 RSA/ECDSA encryption and asynchronous/deferred signing
35 - Text drawing with automatic CID encoding generation and font subsetting
36 - Full-featured low-level Unicode text extraction
37 - Advanced CJK language support (text extraction and automatic multi-byte encoding)
38 - PDF/A compliance preservation (e.g., font embedding, simultaneous PDF/A and PDF/UA compliance)
39 - PDF/UA compliance preservation (e.g., when adding annotations/form fields)
40 - Deferred font file data embedding
41
42 PoDoFo does not support rendering PDF content yet. Text writing
43 is also limited as it currently does not perform proper text shaping/kerning.
44
45 ## Requirements
46
47 To build PoDoFo lib you'll need a c++17 compiler,
48 CMake 3.23 and the following libraries (tentative minimum versions indicated):
49
50 * freetype2 (2.11)
51 * fontconfig (2.13.94, required for Unix platforms, optional for Windows)
52 * OpenSSL (1.1 and 3.0 are supported)
53 * LibXml2 (2.9.12)
54 * zlib
55 * libjpeg (9d, optional)
56 * libtiff (4.0.10, optional)
57 * libpng (1.6.37, optional)
58
59 For the most popular toolchains, PoDoFo requires the following
60 minimum versions:
61
62 * msvc++ 14.16 (VS 2017 15.9)
63 * gcc 9.0
64 * clang/llvm 9.0
65 * XCode 11.0
66
67 It is regularly tested with the following IDE/toolchains versions:
68
69 * Visual Studio 2022 17.14
70 * gcc 9.3.1
71 * XCode 15.4
72 * NDK r28
73
74 ## Licensing
75
76 The PoDoFo library is licensed under the [LGPL 2.0 or later](https://spdx.org/licenses/LGPL-2.0-or-later.html) terms or, at your option, [MPL 2.0](https://spdx.org/licenses/MPL-2.0.html).
77
78 PoDoFo tools are licensed under the [GPL 2.0 or later](https://spdx.org/licenses/GPL-2.0-or-later.html) terms.
79
80 Please refer to the [NOTICE](https://github.com/podofo/podofo/blob/master/NOTICE) file for the use of 3rd party components. Consider disabling the [AFDKO](https://github.com/adobe-type-tools/afdko) integration if you plan to distribute the PoDoFo library with [GPL 2.0-only](https://spdx.org/licenses/GPL-2.0-only.html) projects.
81
82 ## Development quickstart
83
84 PoDoFo is known to compile through a multitude of package managers (including [APT](https://en.wikipedia.org/wiki/APT_(software)), [brew](https://brew.sh/), [vcpkg](https://vcpkg.io/), [Conan](https://conan.io/)), and has public continuous integration working in [Ubuntu Linux](https://github.com/podofo/podofo/blob/master/.github/workflows/build-linux.yml), [MacOS](https://github.com/podofo/podofo/blob/master/.github/workflows/build-linux.yml) and
85 [Windows](https://github.com/podofo/podofo/blob/master/.github/workflows/build-win.yml), bootstrapping the CMake project, building and testing the library. It's highly recommended to build PoDoFo using such package managers.
86
87 There's also a playground area in the repository where you can have
88 access to pre-built dependencies for some popular architectures/operating systems:
89 the playground is the recommended setting to develop the library and reproduce bugs,
90 while it's not recommended for the deployment of your application using PoDoFo.
91 Have a look to the [Readme](https://github.com/podofo/podofo/tree/master/playground) there.
92
93 > **Warning**: PoDoFo is known to be working in cross-compilation toolchains (eg. Android/iOS development), but support may not provided in such scenarios. If you decide to manually build dependencies you are assumed to know how to identity possible library clashes/mismatches and how to deal with compilation/linking problems that can arise in your system.
94
95 ### Build with APT
96
97 From the source root run:
98
99 ```
100 sudo apt install -y libfontconfig1-dev libfreetype-dev libxml2-dev libssl-dev libjpeg-dev libpng-dev libtiff-dev
101 mkdir build
102 cd build
103 cmake -DCMAKE_BUILD_TYPE=Debug ..
104 cmake --build . --config Debug
105 ```
106
107 ### Build with brew
108
109 Install [brew](https://brew.sh/), then from the source root run:
110
111 ```
112 brew install fontconfig freetype openssl libxml2 jpeg-turbo libpng libtiff cmake
113 mkdir build
114 cd build
115 cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_FIND_FRAMEWORK=NEVER -DCMAKE_PREFIX_PATH=`brew --prefix` -DFontconfig_INCLUDE_DIR=`brew --prefix fontconfig`/include -DOPENSSL_ROOT_DIR=`brew --prefix openssl@3` ..
116 cmake --build . --config Debug
117 ```
118
119 ### Build with Conan
120
121 Install [conan](https://docs.conan.io/1/installation.html), then from source root run:
122
123 ```
124 mkdir build
125 cd build
126 conan install ..
127 cmake -DCMAKE_BUILD_TYPE=Debug ..
128 cmake --build . --config Debug
129 ```
130
131 ### Build with vcpkg
132
133 Follow the vcpkg [quickstart](https://vcpkg.io/en/getting-started.html) guide to setup the package manager repository first.
134 In Windows, it may be also useful to set the environment variable `VCPKG_DEFAULT_TRIPLET` to `x64-windows` to default installing 64 bit dependencies
135 and define a `VCPKG_ROOT` variable with the location of the repository as created in the quickstart.
136
137 Then from source root run:
138
139 ```
140 vcpkg install
141 mkdir build
142 cmake "-DCMAKE_TOOLCHAIN_FILE=vcpkg.cmake" -DCMAKE_BUILD_TYPE=Debug -B build
143 cmake --build build --config Debug
144 ```
145
146 ### Consume PoDoFo from package managers with CMake
147
148 Starting with version 1.0, PoDoFo has a quite advanced CMake integration and can be consumed
149 as a [CMake package](https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html).
150 As soon as it's correctly integrated in your favorite package manager (APT, vcpkg, Conan,
151 ...), you will be able to locate PoDoFo and compile your application with the following
152 `CMakeLists.txt`:
153
154 ```
155 cmake_minimum_required(VERSION 3.23)
156
157 project(PoDoFoSample)
158
159 # PoDoFo public header requires at least C++17,
160 # but it can be used with higher standards
161 set(CMAKE_CXX_STANDARD 23)
162
163 # If you are not using a package manager and/or you
164 # are installing PoDoFo to a non-standard path
165 #list(APPEND CMAKE_PREFIX_PATH "/path/to/podofo_install_dir")
166
167 find_package(PoDoFo 1.0.0 REQUIRED)
168 message(STATUS "Found PoDoFo: ${PoDoFo_VERSION}")
169
170 add_executable(helloworld main.cpp)
171 target_link_libraries(helloworld podofo::podofo)
172 ```
173
174 ### CMake switches
175
176 - `PODOFO_BUILD_TEST`: Build the unit tests, defaults to TRUE;
177
178 - `PODOFO_BUILD_EXAMPLES`: Build the examples, defaults to TRUE;
179
180 - `PODOFO_BUILD_UNSUPPORTED_TOOLS`: Build the PoDoFo tools, defaults to FALSE. See
181 the relevant [section](https://github.com/podofo/podofo/#podofo-tools) in the Readme;
182
183 - `PODOFO_BUILD_LIB_ONLY`: If TRUE, it will build only the library component.
184 This unconditionally disable building tests, examples and tools;
185
186 - `PODOFO_BUILD_STATIC`: If TRUE, build the library as a static object and use it in tests,
187 examples and tools. By default a shared library is built;
188
189 - `PODOFO_WITH_FONTMANAGER`: Enable search of fonts in the system. It generally requires Fontconfig, unless specific platforms fallbacks are enabled. Defaults to ON;
190
191 - `PODOFO_WITH_WIN32GDI_FONT_SEARCH`: In Windows, enable use of Win32 GDI for font search (Fontconfig is always prefered, if available), defaults to OFF;
192
193 - `PODOFO_WITH_AFDKO`: Enable the [Adobe Font Development Kit for OpenType](https://github.com/adobe-type-tools/afdko) integration (used in Type1/OpenType font subsetting), defaults to ON;
194
195 - `PODOFO_DEVENDOR_TCBSPAN`: If TRUE, the [`tcb::span`](https://github.com/tcbrindle/span) library will be devendored;
196
197 - `PODOFO_DEVENDOR_DATE`: If TRUE, the [`date`](https://github.com/howardhinnant/date) library will be devendored;
198
199 - `PODOFO_DEVENDOR_FASTFLOAT`: If TRUE, the [`fast_float`](https://github.com/fastfloat/fast_float) library will be devendored;
200
201 - `PODOFO_DEVENDOR_FMT`: If TRUE, the [`fmt`](https://github.com/fmtlib/fmt) library will be devendored;
202
203 - `PODOFO_DEVENDOR_FMT_HEADER_ONLY`: Implies `PODOFO_DEVENDOR_FMT`, but uses the `fmt::fmt-header-only` library flavour;
204
205 - `PODOFO_DEVENDOR_UTF8CPP`: If TRUE, the [`utf8cpp`](https://github.com/nemtrif/utfcpp) library will be devendored;
206
207 - `PODOFO_DEVENDOR_UTF8PROC`: If TRUE, the [`utf8proc`](https://juliastrings.github.io/utf8proc/) library will be devendored.
208
209 ### Static linking
210
211 If you want to use a static build of PoDoFo and you are including the PoDoFo cmake project it's very simple. Do something like the following in your CMake project:
212
213 ```
214 set(PODOFO_BUILD_LIB_ONLY TRUE CACHE BOOL "" FORCE)
215 set(PODOFO_BUILD_STATIC TRUE CACHE BOOL "" FORCE)
216 add_subdirectory(podofo)
217 # ...
218 target_link_libraries(MyTarget podofo::podofo)
219 ```
220
221 If you are linking against a precompiled static build of PoDoFo this is a scenario where the support is limited, as you are really supposed to be able to identify and fix linking errors. The general steps are:
222 * Add `PODOFO_STATIC` compilation definition to your project, or before including `podofo.h`;
223 * Link the libraries `podofo.a`, `podofo_private.a`, `podofo_3rdparty.a` (`podofo.lib`, `podofo_private.lib`, `podofo_3rdparty.lib` in MSVC) and all the [dependent](https://github.com/podofo/podofo/blob/5a07b90f24747a5aafe6f6fd062ee81f4783ab22/CMakeLists.txt#L203C5-L203C24) libraries.
224
225 ## Doxygen Documentation
226
227 The API documentation can be found at https://podofo.github.io/podofo/documentation/ .
228
229 ### Generate the doxygen documentation
230
231 1. **Prerequisite**: Ensure you have Doxygen installed on your machine. If not, visit [Doxygen's official website](http://www.doxygen.nl/) to download and install it.
232
233 2. **Generating Documentation**: After completing the build process detailed in the [Development quickstart](#development-quickstart) chapter, navigate to the root directory of PoDoFo's source code.
234 Open a terminal or command prompt and run the following command:
235 ```bash
236 doxygen build/Doxyfile
237 ```
238
239 3. **Viewing the Documentation**: Once the documentation generation completes, you'll find a `documentation` directory that contains the generated documentation. Open `index.html` in your favorite web browser to view the API documentation.
240 ```bash
241 cd build/doxygen/documentation
242 open index.html
243 ```
244 ## Software life cycle and API stability
245
246 Refer to the main article in the [Wiki](https://github.com/podofo/podofo/wiki/Home).
247 At this [page](https://github.com/podofo/podofo/blob/master/API-MIGRATION.md) you can find an incomplete guide on migrating 0.9.8 code to 0.10.x, and from 0.10.x to 1.0.
248
249 ## String encoding and buffer conventions
250
251 All `std::strings` or `std::string_view` in the library are intended
252 to hold UTF-8 encoded string content. `PdfString` and `PdfName` constructors
253 accept UTF-8 encoded strings by default (`PdfName` accept only characters in the
254 `PdfDocEncoding` char set, though). `charbuff` and `bufferview`
255 instead represent a generic octet buffer.
256
257 ## Thread safety
258
259 For the most part PoDoFo is not a thread safe library. As a general rule: use any object on the same thread it was created on.
260 Alternatively: guard access to objects obtained through a `PdfDocument` using a mutex. Explicit support is provided for freeing
261 object instances in different threads, as is done in modern garbage collected languages.
262
263 ## PoDoFo Tools
264
265 > **Warning**: Tools are currently **unsupported**, **untested** and **unmaintained**.
266
267 PoDoFo tools are still available in the source [tree](https://github.com/podofo/podofo/)
268 but their compilation is disabled by default because they are unsted/unmaintained,
269 and will not receive support until their status is cleared. It's not recommended to include them in software distributions.
270 If you want to build them make sure to bootstrap the CMake project with ```-DPODOFO_BUILD_UNSUPPORTED_TOOLS=TRUE```.
271 Tools are conveniently enabled in the [playground](https://github.com/podofo/podofo/tree/master/playground)
272 at least to ensure library changes won't break their compilation.
273
274 ## TODO
275
276 There's a [TODO](https://github.com/podofo/podofo/blob/master/TODO.md) list, or look
277 at the [issue](https://github.com/podofo/podofo/issues) tracker.
278
279 ## FAQ
280
281 **Q: PoDoFo compilation requires a CMake version higher than what is present in my system, can you lower the requirement?<a id='faq-cmake'></a>**
282
283 **A:** No, CMake 2.23 introduced a functionality that makes it very easy to create [CMake packages](https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html) that
284 is too convenient to ignore. In Windows it's easy to upgrade the CMake version to latest, while in MacOS it's the same thanks to the official KitWare installer or `brew`.
285 In a linux system it's also quite easy to install an upgraded parallel CMake installation. Just run the following script:
286
287 ```
288 export CMAKE_VERSION=3.31.7 \
289 && wget -nv https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/cmake-${CMAKE_VERSION}-Linux-x86_64.sh \
290 && chmod +x cmake-${CMAKE_VERSION}-Linux-x86_64.sh \
291 && ./cmake-${CMAKE_VERSION}-Linux-x86_64.sh --prefix=/usr/local --skip-license \
292 && rm cmake-${CMAKE_VERSION}-Linux-x86_64.sh \
293 && cmake --version
294 ```
295
296 **Q: How do I sign a document?<a id='faq-sign'></a>**
297
298 **A:** PoDoFo HEAD now supplies a high level signing procedure which is very powerful
299 and that allows to sign a document without having to supply a *CMS* structure manually.
300 By default, it supports signing a document with the modern [`PAdES-B`](https://en.wikipedia.org/wiki/PAdES)
301 compliance profiles, but there's also a support for the legacy PKCS7 signatures.
302 Providing you have both ASN.1 encoded X509 certificate and RSA private key, you
303 can sign a document with the following code:
304
305 ```cpp
306 auto inputOutput = std::make_shared<FileStreamDevice>(filepath, FileMode::Open);
307
308 PdfMemDocument doc;
309 doc.Load(inputOutput);
310
311 auto& page = doc.GetPages().GetPageAt(0);
312 auto& signature = page.CreateField<PdfSignature>("Signature", Rect());
313
314 auto signer = PdfSignerCms(x509certbuffer, pkeybuffer);
315 PoDoFo::SignDocument(doc, *inputOutput, signer, signature);
316 ```
317
318 There's also a support for external signing services and/or signing the document
319 in memory buffers. See the various signing examples in the unit [tests](https://github.com/podofo/podofo/blob/master/test/unit/SignatureTest.cpp).
320
321 **Q: Can I still use an event based procedure to sign the document?<a id='faq-sign-event-based'></a>**
322
323 **A:** Yes, the old low level procedure hasn't changed and it's still available.
324 To describe the procedure briefly, one has to fully Implement a `PdfSigner`,
325 retrieve or create a `PdfSignature` field, create an output device (see next question)
326 and use `PoDoFo::SignDocument(doc, device, signer, signature)`. When signing,
327 the sequence of calls of `PdfSignature` works in this way: method `PdfSigner::Reset()`
328 is called first, then the `PdfSigner::ComputeSignature(buffer, dryrun)` is called with
329 an empty buffer and the `dryrun` argument set to `true`. In this call one can just
330 resize the buffer overestimating the required size for the signature, or just
331 compute a fake signature that must be saved on the buffer. Then a sequence of
332 `PdfSigner::AppendData(buffer)` are called, receiving all the document data to
333 be signed. A final `PdfSigner::ComputeSignature(buffer, dryrun)` is called, with
334 the `dryrun` parameter set to `false`. The buffer on this call is cleared (capacity
335 is not altered) or not accordingly to the value of `PdfSigner::SkipBufferClear()`.
336
337
338 **Q: `PdfMemDocument::SaveUpdate()` or `PoDoFo::SignDocument()` write only a
339 partial file: why there's no mechanism to seamlessly handle the incremental
340 update as it was in PoDoFo 0.9.x? What should be done to correctly update/sign
341 the document?<a id='faq-manual-update'></a>**
342
343 **A:** The previous mechanism in PoDoFo 0.9.x required enablement of document
344 for incremental updates, which is a decision step which I believe should be
345 unnecessary. Also:
346 1. In case of file loaded document it still required to perform the update in
347 the same file, and the check was performed on the path of the files being
348 operated to, which is unsafe;
349 2. In case of buffers worked for one update/signing operation but didn't work
350 for following operations, meaning the mechanism was bugged/unreliable.
351
352 An alternative strategy that makes clearer the fact that the incremental update
353 must be performed on the same file from where the document was loaded, or that underlying
354 buffer will grow its memory consumption following subsequent operations in case of
355 buffer loaded documents, is available. It follows a couple of examples showing the
356 correct operations to update a document, loaded from file or buffer:
357
358 1. Save an update on a file loaded document, by loading and saving the document on the same location:
359
360 ```cpp
361 auto inputOutput = std::make_shared<FileStreamDevice>(filename, FileMode::Open);
362
363 PdfMemDocument doc;
364 doc.Load(inputOutput);
365
366 doc.SaveUpdate(*inputOutput);
367 ```
368
369 2. Save an update on a buffer, by copying the source first to the buffer
370 that will be also used to load the document:
371
372 ```cpp
373 charbuff outputBuffer;
374 FileStreamDevice input(filepath);
375 auto inputOutput = std::make_shared<BufferStreamDevice>(outputBuffer);
376 input.CopyTo(*inputOutput);
377
378 PdfMemDocument doc;
379 doc.Load(inputOutput);
380
381 doc.SaveUpdate(*inputOutput);
382 ```
383
384 Signing documents can be done with same technique, read the other questions for more examples.
385
386 **Q: Can I sign a document a second time?<a id='faq-sign-second'></a>**
387
388 **A:** Yes, this is tested, but to make sure this will work you'll to re-parse the document a second time,
389 as reusing the already loaded document is still untested (this may change later). For example you can
390 do as it follows:
391
392 ```cpp
393 auto inputOutput = std::make_shared<FileStreamDevice>(filepath, FileMode::Open);
394
395 {
396 PdfMemDocument doc;
397 doc.Load(inputOutput);
398 auto& page = doc.GetPages().GetPageAt(0);
399 auto& signature = page.CreateField<PdfSignature>("Signature1", Rect());
400
401 PdfSignerCms signer(x509certbuffer, pkeybuffer);
402 PoDoFo::SignDocument(doc, *inputOutput, signer, signature);
403 }
404
405 {
406 PdfMemDocument doc;
407 doc.Load(inputOutput);
408 auto& page = doc.GetPages().GetPageAt(0);
409 auto& signature = page.CreateField<PdfSignature>("Signature2", Rect());
410 PdfSignerCms signer(x509certbuffer, pkeybuffer);
411 PoDoFo::SignDocument(doc, *inputOutput, signer, signature);
412 }
413 ```
414
415 ## No warranty
416
417 PoDoFo may or may not work for your needs and comes with absolutely no
418 warranty. Serious bugs, including security flaws, may be fixed at arbitrary
419 timeframes, or not fixed at all. Priority of implementing new features
420 and bug fixing are decided according to the interests and personal
421 preferences of the maintainers. If you need PoDoFo to integrate a feature
422 or bug fix that is critical to your workflow, the most welcome and fastest
423 approach is to [contribute](https://github.com/podofo/podofo/edit/master/README.md#contributions)
424 high-quality patches.
425
426 ## Contributions
427
428 Please subscribe to the project mailing [list](https://sourceforge.net/projects/podofo/lists/podofo-users)
429 which is still followed by several of the original developers of PoDoFo.
430 A Discord [server](https://discord.gg/t9xX77ZrHr) has also been created to ease some more informal chatter.
431 If you find a bug and know how to fix it, or you want to add a small feature, you're welcome to send a [pull request](https://github.com/podofo/podofo/pulls),
432 providing it follows the [coding style](https://github.com/podofo/podofo/blob/master/CODING-STYLE.md)
433 of the project. As a minimum requisite, any contribution should be:
434 * valuable for a multitude of people and not only self relevant for the contributor;
435 * consistent with surrounding code and not result in unpredictable behavior and/or bugs.
436
437 Other reasons for the rejection, or hold, of a pull request may be:
438
439 * the proposed code is incomplete or hacky;
440 * the change doesn't fit the scope of PoDoFo;
441 * the change shows lack of knowledge/mastery of the PDF specification and/or C++ language;
442 * the change breaks automatic tests performed by the maintainer;
443 * general lack of time in reviewing and merging the change.
444
445 If you need to implement a bigger feature or refactor, ask first if
446 it was already planned. The feature may be up for grabs, meaning that it's open for external contributions.
447 Please write in the relevant issue that you started to work on that, to receive some feedback/coordination.
448 If it's not, it means that the refactor/feature is planned to be implemented later by the maintainer(s).
449 If the feature is not listed in the issues, add it and/or create a [discussion](https://github.com/podofo/podofo/discussions)
450 to receive some feedback and discuss some basic design choices.
451
452 ## Authors
453
454 > **Warning**: Please don't use personal email addresses for technical support inquries, but create
455 github [issues](https://github.com/podofo/podofo/issues) instead.
456
457 PoDoFo is currently developed and maintained by
458 [Francesco Pretto](mailto:[email protected]), together with Dominik Seichter and others. See the file
459 [AUTHORS.md](https://github.com/podofo/podofo/blob/master/AUTHORS.md) for more details.
460