| 1 |
# AGENTS.md |
| 2 |
|
| 3 |
## Project overview |
| 4 |
|
| 5 |
PoDoFo is a C++17 library for reading, writing and manipulating PDF documents. The build configuration is handled by CMake. The library can be built as shared (default) or static (`-DPODOFO_BUILD_STATIC=TRUE`). |
| 6 |
Required toolchains (minimum versions): |
| 7 |
- CMake 3.23 |
| 8 |
- GCC 9 |
| 9 |
- Clang 9 |
| 10 |
- Apple Clang 11 |
| 11 |
- MSVC 15.9 |
| 12 |
|
| 13 |
## Source layout |
| 14 |
|
| 15 |
``` |
| 16 |
src/podofo/ |
| 17 |
├── main/ Core public API classes (PdfDocument, PdfPage, PdfFont, ...) |
| 18 |
├── auxiliary/ General-purpose types not specific to PDF (nullable, cspan, mspan, StreamDevice, ...) |
| 19 |
├── optional/ PDF-specific helpers not pulled in by podofo.h |
| 20 |
├── staging/ Unstable API under development |
| 21 |
├── private/ Internal implementation (podofo_private static lib target) |
| 22 |
├── 3rdparty/ Vendored 3rd-party headers, conditionally part of the public API (tcb::span) |
| 23 |
└── podofo.h Umbrella public include |
| 24 |
``` |
| 25 |
|
| 26 |
- `3rdparty/` vendored headers/sources (fmtlib, fast_float, utf8cpp, date, tcb::span, chromium numerics, Adobe AFDKO) |
| 27 |
- `test/unit/`: Catch2-based unit tests (single executable `podofo-unit`) |
| 28 |
- `test/common/`: shared test utilities (`PdfTest.h`, `TestUtils`) |
| 29 |
- `tools/`: CLI utilities built on top of the library |
| 30 |
- `examples/`: simple sample programs |
| 31 |
- `playground/`: development and test bed using pre-built dependencies |
| 32 |
- `extern/resources/`: test fixture files (git submodule) |
| 33 |
- `extern/deps/`: depedencies for the `playground` (git submodule) |
| 34 |
|
| 35 |
## Dependencies |
| 36 |
|
| 37 |
Required: zlib, OpenSSL, FreeType, libxml2, Fontconfig (on Windows it can be optional with `PODOFO_WITH_WIN32GDI_FONT_SEARCH` option enabled) |
| 38 |
|
| 39 |
Optional: libjpeg, libpng, libtiff |
| 40 |
|
| 41 |
Vendored: fmt, fast_float, utf8cpp, utf8proc, tcb-span, date |
| 42 |
|
| 43 |
## Building and running test |
| 44 |
|
| 45 |
It's recommented to use the `playground`. First ensure `extern/{deps|resources}` are fetched. If not, do it before continuing: |
| 46 |
|
| 47 |
``` |
| 48 |
git submodule update --init |
| 49 |
``` |
| 50 |
|
| 51 |
The `playground` shall be used with a CMake build dir named accordingly to the host platform and build type as described in the commands below. Prefer debug builds while testing. |
| 52 |
|
| 53 |
### Bootstrap: |
| 54 |
|
| 55 |
``` |
| 56 |
cd playground |
| 57 |
cmake -B build-{win|linux|macos}-{Debug|Release} -DCMAKE_BUILD_TYPE={Debug|Release} |
| 58 |
``` |
| 59 |
### Build: |
| 60 |
``` |
| 61 |
cmake --build build-{win|linux|macos}-{Debug|Release} |
| 62 |
``` |
| 63 |
|
| 64 |
### Run unit tests: |
| 65 |
|
| 66 |
``` |
| 67 |
ctest --test-dir build-{win|linux|macos}-{Debug|Release} |
| 68 |
``` |
| 69 |
|
| 70 |
The test executable is `build-{win|linux|macos}-{Debug|Release}/target/podofo-unit`. |
| 71 |
|
| 72 |
## CMake targets |
| 73 |
|
| 74 |
- `podofo_shared` / `podofo_static`: Main library (aliased as `podofo::podofo`) |
| 75 |
- `podofo_private`: Internal static library with private implementation details |
| 76 |
- `podofo_3rdparty`: Vendored 3rd-party code compiled as a static library |
| 77 |
- `podofo-unit`: Unit test executable |
| 78 |
|
| 79 |
## Coding style |
| 80 |
|
| 81 |
#[[file:CODING-STYLE.md]] |
| 82 |
|
| 83 |
Refer to `CODING-STYLE.md`, but don't follow any hyperlink there. In addition: |
| 84 |
- never use Em Dash when writing, just the regular ASCII hyphen `-` |
| 85 |
- never use Horizontal Ellipsis when writing, just regular ASCII dots `...` |
| 86 |
|
| 87 |
## Key classes |
| 88 |
|
| 89 |
- `PdfMemDocument`: in-memory document loaded from file or buffer |
| 90 |
- `PdfStreamedDocument`: write-only streaming document |
| 91 |
- `PdfPage` / `PdfPageCollection`: page access and manipulation |
| 92 |
- `PdfObject` / `PdfVariant`: the generic PDF object model |
| 93 |
- `PdfDictionary` / `PdfArray` / `PdfName` / `PdfString`: PDF data types |
| 94 |
- `PdfElement`: a wrapper for a `PdfDictionary` or `PdfArray` within a document. Can be extended to add functionalities |
| 95 |
- `PdfFont` / `PdfFontManager`: font loading, subsetting and encoding |
| 96 |
- `PdfPainter`: high-level drawing API (paths, text, images) |
| 97 |
- `PdfEncoding` / `PdfEncodingMap`: character code <-> Unicode mapping |
| 98 |
- `PdfEncrypt` / `PdfSigningContext`: digital signatures |
| 99 |
|
| 100 |
## Developing steering |
| 101 |
|
| 102 |
- No excess tests: one or two simple tests per small fix/feature are usually fine, unless exhaustive coverage is genuinely needed |
| 103 |
- If a PDF fixture is needed in a test, it should be precomputed as a constant string, not assembled on the fly with text-writing operations |
| 104 |
- Catch2 `SECTION(s)` should be avoided in tests when possible |
| 105 |
- No long, repetitive comments. If a comment must be repeated it should fit on one or two lines at most |
| 106 |
- Test files live in `test/unit/` and follow the naming pattern `<Topic>Test.cpp` |
| 107 |
- Tests include `<PdfTest.h>` (which pulls in Catch2, PoDoFo headers, and `TestUtils`). The macros `ASSERT_EQUAL` and `ASSERT_THROW_WITH_ERROR_CODE` are available for common assertions |
| 108 |
- Test resource files are read via `TestUtils::GetTestInputFilePath(...)` and output goes to `TestUtils::GetTestOutputFilePath(...)` |