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