Debian Codegraph @

podofo/AGENTS.md

raw
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(...)`