PoDoFo

1. What is PoDoFo?
2. Features
3. Requirements
4. Licensing
5. Development quickstart
6. Doxygen Documentation
7. Software life cycle and API stability
8. String encoding and buffer conventions
9. Thread safety
10. PoDoFo tools
11. TODO
12. FAQ
13. No warranty
14. Contributions
15. Authors

What is PoDoFo?

PoDoFo is a free portable C++ library to work with the PDF file format.

PoDoFo provides classes to parse a PDF file and modify its content, allowing to write it back to disk easily. Besides PDF parsing and manipulation PoDoFo also provides facilities to create your own PDF files from scratch.

Features

PoDoFo has a modern and user-friendly C++17 API that features:

• PDF parsing with high-level entity inspection (annotations, form fields and others)
• PDF writing with support for incremental updates
• PDF signing with PAdES-B compliance, RSA/ECDSA encryption and asynchronous/deferred signing
• Text drawing with automatic CID encoding generation and font subsetting
• Full-featured low-level Unicode text extraction
• Advanced CJK language support (text extraction and automatic multi-byte encoding)
• PDF/A compliance preservation (e.g., font embedding, simultaneous PDF/A and PDF/UA compliance)
• PDF/UA compliance preservation (e.g., when adding annotations/form fields)
• Deferred font file data embedding

PoDoFo does not support rendering PDF content yet. Text writing is also limited as it currently does not perform proper text shaping/kerning.

Requirements

To build PoDoFo lib you'll need a c++17 compiler, CMake 3.23 and the following libraries (tentative minimum versions indicated):

• freetype2 (2.11)
• fontconfig (2.13.94, required for Unix platforms, optional for Windows)
• OpenSSL (1.1 and 3.0 are supported)
• LibXml2 (2.9.12)
• zlib
• libjpeg (9d, optional)
• libtiff (4.0.10, optional)
• libpng (1.6.37, optional)

For the most popular toolchains, PoDoFo requires the following minimum versions:

• msvc++ 14.16 (VS 2017 15.9)
• gcc 9.0
• clang/llvm 7.0

It is regularly tested with the following IDE/toolchains versions:

• Visual Studio 2017 15.9
• Visual Studio 2019 16.11
• Visual Studio 2022 17.3
• gcc 9.3.1
• XCode 13.3
• NDK r23b

GCC 8.1 support broke, but it could be reinstanced.

Licensing

PoDoFo library is licensed under the LGPL 2.0 or later terms. PoDoFo tools are licensed under the GPL 2.0 or later terms.

Development quickstart

PoDoFo is known to compile through a multitude of package managers (including APT, brew, vcpkg, Conan), and has public continuous integration working in Ubuntu Linux, MacOS and Windows, bootstrapping the CMake project, building and testing the library. It's highly recommended to build PoDoFo using such package managers.

There's also a playground area in the repository where you can have access to pre-build dependencies for some popular architectures/operating systems: the playground is the recommended setting to develop the library and reproduce bugs, while it's not recommended for the deployment of your application using PoDoFo. Have a look to the Readme there.

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.

Build with APT

From the source root run:

sudo apt install -y libfontconfig1-dev libfreetype-dev libxml2-dev libssl-dev libjpeg-dev libpng-dev libtiff-dev
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug

Build with brew

Install brew, then from the source root run:

brew install fontconfig freetype openssl libxml2 jpeg-turbo libpng libtiff cmake
mkdir build
cd build
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` ..
cmake --build . --config Debug

Build with Conan

Install conan, then from source root run:

mkdir build
cd build
conan install ..
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug

Build with vcpkg

Follow the vcpkg quickstart guide to setup the package manager repository first. In Windows, it may be also useful to set the environment variable VCPKG_DEFAULT_TRIPLET to x64-windows to default installing 64 bit dependencies and define a VCPKG_INSTALLATION_ROOT variable with the location of the repository as created in the quickstart.

Then from source root run:

vcpkg install fontconfig freetype libxml2 openssl libjpeg-turbo libpng tiff zlib
mkdir build
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug

Consume PoDoFo from package managers with CMake

Starting with version 1.0, PoDoFo has a quite advanced CMake integration and can be consumed as a CMake package. As soon as it's correctly integrated in your favorite package manager (APT, vcpkg, Conan, ...), you will be able to locate PoDoFo and compile your application with the following CMakeLists.txt:

cmake_minimum_required(VERSION 3.23)

project(PoDoFoSample)

# PoDoFo public header requires at least C++17,
# but it can be used with higher standards
set(CMAKE_CXX_STANDARD 23)

# If you are not using a package manager and/or you
# are installing PoDoFo to a non-standard path
#list(APPEND CMAKE_PREFIX_PATH "/path/to/podofo_install_dir")

find_package(PoDoFo 1.0.0 REQUIRED)
message(STATUS "Found PoDoFo: ${PoDoFo_VERSION}")

add_executable(helloworld main.cpp)
target_link_libraries(helloworld podofo::podofo)

CMake switches

• PODOFO_BUILD_TEST: Build the unit tests, defaults to TRUE;

• PODOFO_BUILD_EXAMPLES: Build the examples, defaults to TRUE;

• PODOFO_BUILD_UNSUPPORTED_TOOLS: Build the PoDoFo tools, defaults to FALSE. See the relevant section in the Readme;

• PODOFO_BUILD_LIB_ONLY: If TRUE, it will build only the library component. This unconditionally disable building tests, examples and tools;

• PODOFO_BUILD_STATIC: If TRUE, build the library as a static object and use it in tests, examples and tools. By default a shared library is built.

Static linking

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:

set(PODOFO_BUILD_LIB_ONLY TRUE CACHE BOOL "" FORCE)
set(PODOFO_BUILD_STATIC TRUE CACHE BOOL "" FORCE)
add_subdirectory(podofo)
# ...
target_link_libraries(MyTarget podofo::podofo)

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:

• Add PODOFO_STATIC compilation definition to your project, or before including podofo.h;
• 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 libraries.

Doxygen Documentation

The API documentation can be found at https://podofo.github.io/podofo/documentation/ .

Generate the doxygen documentation

1. Prerequisite: Ensure you have Doxygen installed on your machine. If not, visit Doxygen's official website to download and install it.

2. Generating Documentation: After completing the build process detailed in the Development quickstart chapter, navigate to the root directory of PoDoFo's source code. Open a terminal or command prompt and run the following command:

   doxygen build/Doxyfile
   

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.

   cd build/doxygen/documentation
   open index.html
   

Software life cycle and API stability

Refer to the main article in the [Wiki]