PDFium

前提条件

PDFium 使用与 Chromium 相同的构建工具。请参阅特定平台的 Chromium 构建说明以开始操作，但需将 Chromium 的“获取代码”说明替换为 PDFium 的说明。

• Chromium Linux 构建说明
• Chromium Mac 构建说明
• Chromium Windows 构建说明

支持的 CPU 架构

Windows、Linux 和 Mac 的默认架构为“x64”。在 Windows 上，“x86”也受支持。可使用 GN 参数“target_cpu = "x86"”覆盖默认值。如果指定 Android 构建，默认 CPU 架构将为“arm”。

预计代码中仍有部分地方在大端序架构上无法正常运行。欢迎报告错误和/或提交补丁，但是目前提供此支持并非优先事项。

支持的编译器

PDFium 旨在符合 Chromium 政策。

目前这意味着支持 Clang。以前使用 MSVC 的用户如需继续使用，可考虑使用 clang-cl。社区贡献的 gcc 补丁将被允许。不接受 MSVC 补丁。

Google 员工

运行：download_from_google_storage --config 并按照身份验证说明进行操作。请注意，您必须使用 @google.com 凭据进行身份验证。如果被问及项目 ID，请输入“0”。

完成此步骤后，工具链将在下面的生成构建文件步骤中自动为您安装。

工具链将位于 depot_tools\win_toolchain\vs_files\<hash>，windbg 可在 depot_tools\win_toolchain\vs_files\<hash>\win_sdk\Debuggers 中找到。

如果您需要用于调试和编辑的 IDE，则需要单独安装，但这是可选的，构建 PDFium 不需要此步骤。

获取代码

顶级目录的名称无关紧要。在以下示例中，目录名称为 “repo”。此目录之前不得被 gclient config 使用过，因为每个目录只能包含一个 gclient 配置。

mkdir repo
cd repo
gclient config --unmanaged https://pdfium.googlesource.com/pdfium.git
gclient sync
cd pdfium

在 Linux 上，需要通过从 pdfium 目录运行以下命令来安装额外的构建依赖项。

./build/install-build-deps.sh

生成构建文件

PDFium 使用 GN 生成构建文件，并通过 Ninja 执行构建文件。这两个工具均包含在 depot_tools 检出内容中。

选择构建配置

PDFium 可以选择启用或禁用 JavaScript 支持，以及启用或禁用 XFA 表单支持。这两项功能默认均为启用状态。请注意，XFA 功能依赖 JavaScript。

通过执行 gn args <directory> 命令进行配置，这将启动编辑器，您可以在其中设置以下参数。按照惯例，<directory> 应命名为 out/foo，部分工具/测试支持代码仅在遵循此惯例时才能正常工作。典型的 <directory> 名称为 out/Debug。

use_remoteexec = false # Approved users only.  Do necessary setup & authentication first.
is_debug = true  # Enable debugging features.

# Set true to enable experimental Skia backend.
pdf_use_skia = false

# Set true to enable experimental Fontations backend.
pdf_enable_fontations = false

pdf_enable_xfa = true  # Set false to remove XFA support (implies JS support).
pdf_enable_v8 = true  # Set false to remove Javascript support.
pdf_is_standalone = true  # Set for a non-embedded build.
is_component_build = false # Disable component build (Though it should work)

为了让 pdfium_test 等测试应用能够构建，必须设置 pdf_is_standalone = true。

默认情况下，整个项目使用 C++20 构建。

默认情况下，PDFium 期望使用提供额外 chrome 插件的 clang 编译器进行构建。若要使用缺少这些插件的普通 clang 编译器进行构建，必须设置 clang_use_chrome_plugins = false。

完成后，参数将存储在 <directory>/args.gn 中，GN 将自动使用这些新参数生成构建文件。如果文件生成失败，请仔细检查是否已按上述说明设置 use_sysroot。

构建代码

你可以通过运行以下命令构建独立测试程序： ninja -C <directory> pdfium_test 你可以通过运行以下命令构建整个产品（包括一些单元测试）： ninja -C <directory> pdfium_all

运行独立测试程序

pdfium_test 程序支持读取、解析 PDF 文件的页面，并将其光栅化为 .ppm 或 .png 输出图像文件（Windows 支持另外两种格式）。例如：<directory>/pdfium_test --ppm path/to/myfile.pdf。请注意，这会将输出图像写入 path/to/myfile.pdf.<n>.ppm。运行 pdfium_test --help 以查看所有选项。

测试

目前有几个可以运行的测试套件：

• pdfium_unittests
• pdfium_embeddertests
• testing/tools/run_corpus_tests.py
• testing/tools/run_javascript_tests.py
• testing/tools/run_pixel_tests.py

由于不同平台上的字体差异，testing 目录中的测试可能会失败。这些测试在自动化构建机上是可靠的。如果你遇到失败，在最新代码 checkout 上运行测试，看看是否出现相同的失败，这可能是个好主意。

像素测试

如果你的更改影响渲染，则应添加像素测试。只需在 testing/resources/pixel 中添加一个 .in 或 .pdf 文件，像素测试运行器将在下次运行时自动检测到它。

确保你的测试用例没有任何版权问题。它还应该是一个最小化的测试用例，专注于在许多 PDF 查看器中以相同方式呈现的 bug。尽量避免流中的二进制数据，使用 ASCIIHexDecode，因为这会使 PDF 在文本编辑器中更具可读性。

要试用你的新测试，你可以调用 run_pixel_tests.py 脚本：

$ ./testing/tools/run_pixel_tests.py your_new_file.in

要生成预期图像，您可以使用 make_expected.sh 脚本：

$ ./testing/tools/make_expected.sh your_new_file.pdf

请确保已安装 optipng，它可以优化生成的 png 文件大小。

.in 文件

.in 文件是 PDF 模板文件。PDF 文件包含许多字节偏移量，这些偏移量必须保持正确，否则文件将无效。模板通过用特定关键字替换字节偏移量，使这一过程变得更加简单。

这样做不仅节省空间，还提供了一种将测试用例精简到最基本要素的简便方法，您只需删除所有非必要内容即可。

简单示例可在此处找到：here。

要将其转换为 PDF，您可以使用 fixup_pdf_template.py 工具：

$ ./testing/tools/fixup_pdf_template.py your_file.in

这将在 your_file.in 所在的同一目录中创建一个 your_file.pdf。

目前没有针对 .in 文件的官方样式指南，但为了提高可读性，建议保持一致的样式。如果可能，对象编号应连续，并且 /Type 和 /SubType 应位于字典的顶部，以便更轻松地识别对象。

在您自己的项目中嵌入 PDFium

public/ 目录包含可供 PDFium 嵌入者使用的 API 头文件。PDFium 项目致力于保持这些 API 的稳定性。

在 public/ 目录之外，代码可能随时发生变化，嵌入者不应直接调用这些例程。

代码覆盖率

可以在 Linux 开发环境中生成 PDFium 的代码覆盖率报告。详细信息可参见此处。

Chromium 提供了 PDFium 的代码覆盖率报告，可通过此处访问。在 Chromium 的源代码中，PDFium 位于 third_party/pdfium。这包括来自 PDFium 模糊测试器的代码覆盖率。

持续构建状态（Waterfall）

源代码树的当前健康状态可在此处查看。

社区

已建立了多个邮件列表：

• PDFium
• PDFium 代码审查
• PDFium 缺陷

请注意，代码审查和缺陷列表通常是只读的。

缺陷

PDFium 使用此缺陷跟踪器，但对于安全缺陷，请使用Chromium 的安全缺陷模板。

代码贡献

有关为 PDFium 项目贡献代码的更多信息，请参见CONTRIBUTING文档。