blob: d867e4cce1875dcbb20cf05206bfba70e3751abe [file] [log] [blame] [view]
dan sinclair1e27a0e2015-10-16 11:59:22 -04001# PDFium
Tom Sepez20ab0232015-09-22 08:52:52 -07002
3## Prerequisites
4
Lei Zhang72fd6562021-05-10 20:33:26 +00005PDFium 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).
Tom Sepez20ab0232015-09-22 08:52:52 -07008
Lei Zhang72fd6562021-05-10 20:33:26 +00009* [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)
weilie7ca8ba2016-04-29 12:04:30 -070012
weilida4ff182016-10-31 13:19:08 -070013### 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
Tom Sepez93e67c92017-08-29 15:09:41 -070020It 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.
dsinclairab522f92016-05-04 11:23:52 -070023
weilie7ca8ba2016-04-29 12:04:30 -070024#### 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
Lei Zhang72fd6562021-05-10 20:33:26 +000031you in the [Generate the build files](#generate-the-build-files) step below.
weilie7ca8ba2016-04-29 12:04:30 -070032
Lei Zhang22a617f2018-10-31 17:57:35 +000033The 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`.
weilie7ca8ba2016-04-29 12:04:30 -070036
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
Tom Sepez20ab0232015-09-22 08:52:52 -070040## Get the code
41
Lei Zhang72fd6562021-05-10 20:33:26 +000042The 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.
Oliver Chang5a21e142015-10-21 15:19:20 -070046
Tom Sepez20ab0232015-09-22 08:52:52 -070047```
Oliver Chang5a21e142015-10-21 15:19:20 -070048mkdir repo
49cd repo
50gclient config --unmanaged https://pdfium.googlesource.com/pdfium.git
Tom Sepez20ab0232015-09-22 08:52:52 -070051gclient sync
Oliver Chang5a21e142015-10-21 15:19:20 -070052cd pdfium
Tom Sepez20ab0232015-09-22 08:52:52 -070053```
54
Lei Zhang72fd6562021-05-10 20:33:26 +000055On Linux, additional build dependencies need to be installed by running the
56following from the `pdfium` directory.
Janee0f13102017-05-23 15:11:45 -040057
58```
59./build/install-build-deps.sh
60```
61
Tom Sepezd20e3882017-04-12 16:06:25 -070062## Generate the build files
Tom Sepez20ab0232015-09-22 08:52:52 -070063
Lei Zhang72fd6562021-05-10 20:33:26 +000064PDFium uses GN to generate the build files and [Ninja](https://ninja-build.org/)
Tom Sepezd20e3882017-04-12 16:06:25 -070065to execute the build files. Both of these are included with the
66depot\_tools checkout.
Tom Sepez20ab0232015-09-22 08:52:52 -070067
weilida4ff182016-10-31 13:19:08 -070068### Selecting build configuration
Tom Sepezd43654a2016-02-04 15:36:13 -080069
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
dsinclairab522f92016-05-04 11:23:52 -070074Configuration is done by executing `gn args <directory>` to configure the build.
dsinclair719a7a72016-05-16 08:11:18 -070075This will launch an editor in which you can set the following arguments.
Lei Zhang01ab0dc2019-01-29 17:31:29 +000076By convention, `<directory>` should be named `out/foo`, and some tools / test
77support code only works if one follows this convention.
Lei Zhang37bc6c62017-05-04 12:16:46 -070078A typical `<directory>` name is `out/Debug`.
Oliver Chang14591ce2015-11-03 13:12:46 -080079
80```
JD Pierce4fcc2402023-05-17 02:46:37 +000081use_goma = false # Googlers only. Ensure goma is installed and running first.
dsinclairab522f92016-05-04 11:23:52 -070082is_debug = true # Enable debugging features.
83
Lei Zhang22a617f2018-10-31 17:57:35 +000084# Set true to enable experimental Skia backend.
85pdf_use_skia = false
dsinclairab522f92016-05-04 11:23:52 -070086
thestig543651f2016-09-01 07:11:45 -070087pdf_enable_xfa = true # Set false to remove XFA support (implies JS support).
dsinclairab522f92016-05-04 11:23:52 -070088pdf_enable_v8 = true # Set false to remove Javascript support.
89pdf_is_standalone = true # Set for a non-embedded build.
Lei Zhangb82b2df2019-05-31 22:41:06 +000090is_component_build = false # Disable component build (Though it should work)
Oliver Chang14591ce2015-11-03 13:12:46 -080091```
92
Lei Zhang22a617f2018-10-31 17:57:35 +000093For sample applications like `pdfium_test` to build, one must set
94`pdf_is_standalone = true`.
95
Lei Zhang3111d402022-04-18 22:24:07 +000096By default, the entire project builds with C++17.
Lei Zhangf02c8c92019-12-05 19:14:23 +000097
Tom Sepez1ce0f042023-05-09 01:53:48 +000098By default, PDFium expects to build with a clang compiler that provides
99additional chrome plugins. To build against a vanilla one lacking these,
100one must set
101`clang_use_chrome_plugins = false`.
102
Tom Sepezd20e3882017-04-12 16:06:25 -0700103When complete the arguments will be stored in `<directory>/args.gn`, and
104GN will automatically use the new arguments to generate build files.
105Should your files fail to generate, please double-check that you have set
106use\_sysroot as indicated above.
dsinclairab522f92016-05-04 11:23:52 -0700107
Tom Sepez20ab0232015-09-22 08:52:52 -0700108## Building the code
109
Lei Zhang37bc6c62017-05-04 12:16:46 -0700110You can build the sample program by running: `ninja -C <directory> pdfium_test`
111You can build the entire product (which includes a few unit tests) by running:
112`ninja -C <directory> pdfium_all`.
Tom Sepez20ab0232015-09-22 08:52:52 -0700113
Tom Sepez20ab0232015-09-22 08:52:52 -0700114## Running the sample program
115
116The pdfium\_test program supports reading, parsing, and rasterizing the pages of
Lei Zhang01ab0dc2019-01-29 17:31:29 +0000117a .pdf file to .ppm or .png output image files (Windows supports two other
dsinclairab522f92016-05-04 11:23:52 -0700118formats). For example: `<directory>/pdfium_test --ppm path/to/myfile.pdf`. Note
dan sinclair1e27a0e2015-10-16 11:59:22 -0400119that this will write output images to `path/to/myfile.pdf.<n>.ppm`.
Lei Zhang01ab0dc2019-01-29 17:31:29 +0000120Run `pdfium_test --help` to see all the options.
dan sinclair1e27a0e2015-10-16 11:59:22 -0400121
122## Testing
123
124There 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
132It is possible the tests in the `testing` directory can fail due to font
133differences on the various platforms. These tests are reliable on the bots. If
134you see failures, it can be a good idea to run the tests on the tip-of-tree
135checkout to see if the same failures appear.
Tom Sepez20ab0232015-09-22 08:52:52 -0700136
Patrik Weiskirchere2a8e9c2019-05-13 19:25:58 +0000137### Pixel Tests
138
139If 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
141pick it up at the next run.
142
143Make sure that your test case doesn't have any copyright issues. It should also
144be a minimal test case focusing on the bug that renders the same way in many
145PDF viewers. Try to avoid binary data in streams by using the `ASCIIHexDecode`
146simply because it makes the PDF more readable in a text editor.
147
148To 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
154To 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
160Please make sure to have `optipng` installed which optimized the file size of
161the resulting png.
162
163### `.in` files
164
165`.in` files are PDF template files. PDF files contain many byte offsets that
166have to be kept correct or the file won't be valid. The template makes this
167easier by replacing the byte offsets with certain keywords.
168
169This saves space and also allows an easy way to reduce the test case to the
170essentials as you can simply remove everything that is not necessary.
171
Lei Zhangb9037bd2021-06-30 17:02:33 +0000172A simple example can be found [here](https://pdfium.googlesource.com/pdfium/+/refs/heads/main/testing/resources/rectangles.in).
Patrik Weiskirchere2a8e9c2019-05-13 19:25:58 +0000173
174To 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
180This will create a `your_file.pdf` in the same directory as `your_file.in`.
181
182There is no official style guide for the .in file, but a consistent style is
183preferred simply to help with readability. If possible, object numbers should
184be consecutive and `/Type` and `/SubType` should be on top of a dictionary to
185make object identification easier.
186
Tom Sepezeb3f4742018-12-21 20:32:48 +0000187## Embedding PDFium in your own projects
188
189The public/ directory contains header files for the APIs available for use by
Lei Zhang72fd6562021-05-10 20:33:26 +0000190embedders of PDFium. The PDFium project endeavors to keep these as stable as
191possible.
Tom Sepezeb3f4742018-12-21 20:32:48 +0000192
193Outside of the public/ directory, code may change at any time, and embedders
194should not directly call these routines.
195
Ryan Harrisonc16df7f2017-07-18 13:44:31 -0400196## Code Coverage
197
198Code coverage reports for PDFium can be generated in Linux development
199environments. Details can be found [here](/docs/code-coverage.md).
200
Lei Zhang01ab0dc2019-01-29 17:31:29 +0000201Chromium 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.
204This includes code coverage from PDFium's fuzzers.
205
Tom Sepez20ab0232015-09-22 08:52:52 -0700206## Waterfall
207
Lei Zhang01ab0dc2019-01-29 17:31:29 +0000208The current health of the source tree can be found
209[here](https://ci.chromium.org/p/pdfium/g/main/console).
Tom Sepez20ab0232015-09-22 08:52:52 -0700210
dan sinclair1e27a0e2015-10-16 11:59:22 -0400211## Community
212
213There 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
219Note, the Reviews and Bugs lists are typically read-only.
220
221## Bugs
222
Lei Zhang72fd6562021-05-10 20:33:26 +0000223PDFium uses this [bug tracker](https://bugs.chromium.org/p/pdfium/issues/list),
224but for security bugs, please use
Lei Zhang01ab0dc2019-01-29 17:31:29 +0000225[Chromium's security bug template](https://bugs.chromium.org/p/chromium/issues/entry?template=Security%20Bug)
dan sinclair1e27a0e2015-10-16 11:59:22 -0400226and add the "Cr-Internals-Plugins-PDF" label.
227
228## Contributing code
229
dan sinclaire7033e72020-06-02 13:41:19 +0000230See the [CONTRIBUTING](CONTRIBUTING.md) document for more information on
231contributing to the PDFium project.