1# PDFium 2 3## Prerequisites 4 5PDFium uses the same build tooling as Chromium. See the platform-specific 6Chromium build instructions to get started, but replace Chromium's 7"Get the code" instructions with [PDFium's](#get-the-code). 8 9* [Chromium Linux build instructions](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/build_instructions.md) 10* [Chromium Mac build instructions](https://chromium.googlesource.com/chromium/src/+/main/docs/mac_build_instructions.md) 11* [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/main/docs/windows_build_instructions.md) 12 13### CPU Architectures supported 14 15The default architecture for Windows, Linux, and Mac is "`x64`". On Windows, 16"`x86`" is also supported. GN parameter "`target_cpu = "x86"`" can be used to 17override the default value. If you specify Android build, the default CPU 18architecture will be "`arm`". 19 20It is expected that there are still some places lurking in the code which will 21not function properly on big-endian architectures. Bugs and/or patches are 22welcome, however providing this support is **not** a priority at this time. 23 24#### Google employees 25 26Run: `download_from_google_storage --config` and follow the 27authentication instructions. **Note that you must authenticate with your 28@google.com credentials**. Enter "0" if asked for a project-id. 29 30Once you've done this, the toolchain will be installed automatically for 31you in the [Generate the build files](#generate-the-build-files) step below. 32 33The toolchain will be in `depot_tools\win_toolchain\vs_files\<hash>`, and 34windbg can be found in 35`depot_tools\win_toolchain\vs_files\<hash>\win_sdk\Debuggers`. 36 37If you want the IDE for debugging and editing, you will need to install 38it separately, but this is optional and not needed for building PDFium. 39 40## Get the code 41 42The name of the top-level directory does not matter. In the following example, 43the directory name is "repo". This directory must not have been used before by 44`gclient config` as each directory can only house a single gclient 45configuration. 46 47``` 48mkdir repo 49cd repo 50gclient config --unmanaged https://pdfium.googlesource.com/pdfium.git 51gclient sync 52cd pdfium 53``` 54 55On Linux, additional build dependencies need to be installed by running the 56following from the `pdfium` directory. 57 58``` 59./build/install-build-deps.sh 60``` 61 62## Generate the build files 63 64PDFium uses GN to generate the build files and [Ninja](https://ninja-build.org/) 65to execute the build files. Both of these are included with the 66depot\_tools checkout. 67 68### Selecting build configuration 69 70PDFium may be built either with or without JavaScript support, and with 71or without XFA forms support. Both of these features are enabled by 72default. Also note that the XFA feature requires JavaScript. 73 74Configuration is done by executing `gn args <directory>` to configure the build. 75This will launch an editor in which you can set the following arguments. 76By convention, `<directory>` should be named `out/foo`, and some tools / test 77support code only works if one follows this convention. 78A typical `<directory>` name is `out/Debug`. 79 80``` 81use_remoteexec = false # Approved users only. Do necessary setup & authentication first. 82is_debug = true # Enable debugging features. 83 84# Set true to enable experimental Skia backend. 85pdf_use_skia = false 86 87# Set true to enable experimental Fontations backend. 88pdf_enable_fontations = false 89 90pdf_enable_xfa = true # Set false to remove XFA support (implies JS support). 91pdf_enable_v8 = true # Set false to remove Javascript support. 92pdf_is_standalone = true # Set for a non-embedded build. 93is_component_build = false # Disable component build (Though it should work) 94``` 95 96For test applications like `pdfium_test` to build, one must set 97`pdf_is_standalone = true`. 98 99By default, the entire project builds with C++20. 100 101By default, PDFium expects to build with a clang compiler that provides 102additional chrome plugins. To build against a vanilla one lacking these, 103one must set 104`clang_use_chrome_plugins = false`. 105 106When complete the arguments will be stored in `<directory>/args.gn`, and 107GN will automatically use the new arguments to generate build files. 108Should your files fail to generate, please double-check that you have set 109use\_sysroot as indicated above. 110 111## Building the code 112 113You can build the standalone test program by running: 114`ninja -C <directory> pdfium_test` 115You can build the entire product (which includes a few unit tests) by running: 116`ninja -C <directory> pdfium_all` 117 118## Running the standalone test program 119 120The pdfium\_test program supports reading, parsing, and rasterizing the pages of 121a .pdf file to .ppm or .png output image files (Windows supports two other 122formats). For example: `<directory>/pdfium_test --ppm path/to/myfile.pdf`. Note 123that this will write output images to `path/to/myfile.pdf.<n>.ppm`. 124Run `pdfium_test --help` to see all the options. 125 126## Testing 127 128There are currently several test suites that can be run: 129 130 * pdfium\_unittests 131 * pdfium\_embeddertests 132 * testing/tools/run\_corpus\_tests.py 133 * testing/tools/run\_javascript\_tests.py 134 * testing/tools/run\_pixel\_tests.py 135 136It is possible the tests in the `testing` directory can fail due to font 137differences on the various platforms. These tests are reliable on the bots. If 138you see failures, it can be a good idea to run the tests on the tip-of-tree 139checkout to see if the same failures appear. 140 141### Pixel Tests 142 143If your change affects rendering, a pixel test should be added. Simply add a 144`.in` or `.pdf` file in `testing/resources/pixel` and the pixel runner will 145pick it up at the next run. 146 147Make sure that your test case doesn't have any copyright issues. It should also 148be a minimal test case focusing on the bug that renders the same way in many 149PDF viewers. Try to avoid binary data in streams by using the `ASCIIHexDecode` 150simply because it makes the PDF more readable in a text editor. 151 152To try out your new test, you can call the `run_pixel_tests.py` script: 153 154```bash 155$ ./testing/tools/run_pixel_tests.py your_new_file.in 156``` 157 158To generate the expected image, you can use the `make_expected.sh` script: 159 160```bash 161$ ./testing/tools/make_expected.sh your_new_file.pdf 162``` 163 164Please make sure to have `optipng` installed which optimized the file size of 165the resulting png. 166 167### `.in` files 168 169`.in` files are PDF template files. PDF files contain many byte offsets that 170have to be kept correct or the file won't be valid. The template makes this 171easier by replacing the byte offsets with certain keywords. 172 173This saves space and also allows an easy way to reduce the test case to the 174essentials as you can simply remove everything that is not necessary. 175 176A simple example can be found [here](https://pdfium.googlesource.com/pdfium/+/refs/heads/main/testing/resources/rectangles.in). 177 178To transform this into a PDF, you can use the `fixup_pdf_template.py` tool: 179 180```bash 181$ ./testing/tools/fixup_pdf_template.py your_file.in 182``` 183 184This will create a `your_file.pdf` in the same directory as `your_file.in`. 185 186There is no official style guide for the .in file, but a consistent style is 187preferred simply to help with readability. If possible, object numbers should 188be consecutive and `/Type` and `/SubType` should be on top of a dictionary to 189make object identification easier. 190 191## Embedding PDFium in your own projects 192 193The public/ directory contains header files for the APIs available for use by 194embedders of PDFium. The PDFium project endeavors to keep these as stable as 195possible. 196 197Outside of the public/ directory, code may change at any time, and embedders 198should not directly call these routines. 199 200## Code Coverage 201 202Code coverage reports for PDFium can be generated in Linux development 203environments. Details can be found [here](/docs/code-coverage.md). 204 205Chromium provides code coverage reports for PDFium 206[here](https://chromium-coverage.appspot.com/). PDFium is located in 207`third_party/pdfium` in Chromium's source code. 208This includes code coverage from PDFium's fuzzers. 209 210## Waterfall 211 212The current health of the source tree can be found 213[here](https://ci.chromium.org/p/pdfium/g/main/console). 214 215## Community 216 217There are several mailing lists that are setup: 218 219 * [PDFium](https://groups.google.com/forum/#!forum/pdfium) 220 * [PDFium Reviews](https://groups.google.com/forum/#!forum/pdfium-reviews) 221 * [PDFium Bugs](https://groups.google.com/forum/#!forum/pdfium-bugs) 222 223Note, the Reviews and Bugs lists are typically read-only. 224 225## Bugs 226 227PDFium uses this [bug tracker](https://bugs.chromium.org/p/pdfium/issues/list), 228but for security bugs, please use 229[Chromium's security bug template](https://bugs.chromium.org/p/chromium/issues/entry?template=Security%20Bug) 230and add the "Cr-Internals-Plugins-PDF" label. 231 232## Contributing code 233 234See the [CONTRIBUTING](CONTRIBUTING.md) document for more information on 235contributing to the PDFium project. 236